OpenAI Agents SDKのguardrailsを置く場所：input・output・tool・handoffの境界

3行まとめ

このテーマをもう少し広げて見るなら、OpenAI Agents SDKのtool guardrailsを実務に入れる前に：handoff・built-in tools・人間承認の分け方 と AIコーディングエージェントのprompt injection対策：Issue・Docs・MCPを読ませる前に決めること も合わせて確認してください。tool call前後の検査やhandoff時の扱いを、この記事のinput/output境界から続けて確認できます。

Input

危険な依頼や対象外入力を早く止めます。

Output

最終返答の形式や漏えいを確認します。

Tool

副作用のあるtool callを前後で確認します。

Human

権限や影響が大きい操作は人へ回します。

agent-levelだけで全経路を守る前提にしないことが出発点です。

• OpenAI Agents SDKのguardrailsは、user input、final output、function tool call、human reviewを分けて置くと、どこで止まるのかを説明しやすくなります。
• input/output guardrailsはagent-levelの入口と出口を見るものです。tool実行ごとの副作用を抑えたい場合は、tool guardrailsや人間承認を別に置きます。
• handoff、hosted tools、built-in execution toolsは通常のfunction toolと同じguardrail境界だと見ない方が安全です。tracingで挙動を確認しつつ、sensitive dataの扱いも先に決めます。

本文の事実確認には、OpenAI Agents SDK公式Docs、Python/JS guardrails Docs、tracing Docs、OpenAI Agents SDK GitHub READMEを使っています。Xで伸びているagent安全性、tool calling、guardrails、handoffへの投稿は需要シグナルとして扱い、本文の根拠にはしていません。

この記事でわかること

境界

input、output、toolの実行点を分けます。

Handoff

移譲時に守れる範囲を確認します。

Approval

人間承認へ回す条件を決めます。

Trace

確認ログとsensitive dataを決めます。

guardrailは機能名より、どの瞬間に止めるかで設計します。

• input guardrailで止めるべきもの
• output guardrailで確認するべきもの
• tool guardrailを置くべき副作用のある処理
• handoffでguardrail境界を過信しない理由
• human reviewへ回す条件
• tracingで確認する項目とsensitive dataの注意

agentの安全設計でよくある失敗は、「guardrailを入れたから大丈夫」とまとめてしまうことです。実際には、入口で止めるべき入力、途中で止めるべきtool call、最後に確認する出力、そもそも自動実行しない操作が分かれます。

この記事では、guardrailsを「どの機能を使うか」ではなく、「どの瞬間に止めたいか」から整理します。

前提知識

項目	内容	見方
Input guardrail		最初のuser inputを確認します。
Output guardrail		最終outputを確認します。
Tool guardrail		function toolの前後を確認します。
Tracing		run、tool、handoff、guardrailを追います。

入口、出口、道中、確認ログを分けて見ます。

OpenAIのAgents SDKガイドでは、SDKはアプリケーション側がorchestration、tool execution、approvals、stateを持つときの選択肢として説明されています。agentはtoolを呼び、specialistへhandoffし、guardrailsやtracingを使いながら複数stepの作業を進めます。

OpenAI Agents SDK Python Docsでは、guardrailsにはinput guardrailsとoutput guardrailsがあり、workflow boundariesとして、input guardrailsはchainの最初のagent、output guardrailsはfinal outputを出すagentに対して動くと説明されています。さらに、function tool invocationごとの確認にはtool guardrailsを使う説明があります。

JS Docsでは、tool guardrailsがfunction toolsに対して、実行前後の検証や拒否を行えること、handoffsやhosted tools、built-in execution toolsでは同じpipelineとして扱わない注意点が説明されています。

この記事の扱う範囲

領域	役割
input guardrail	最初のuser inputを確認する
output guardrail	最終outputを確認する
tool guardrail	custom function toolの前後を確認する
handoff	specialistへ処理を移す
human review	自動実行せず人間へ戻す
tracing	run、tool、handoff、guardrailの挙動を確認する

条件

2026年5月31日時点で公開されている公式Docsを確認しています。SDKの細部はversionで変わるため、実装時にはPython SDK、JS/TS SDKのどちらを使うかと、利用versionを必ず確認してください。

注意点

この記事は攻撃手順や回避手順ではなく、防御と運用設計のための整理です。secret、顧客情報、本番データ、内部ログをagentやtraceへ不用意に渡さない方針を前提にします。

guardrailsを4層に分ける

項目	内容	見方
入口		対象外、危険、コスト高の入力を止めます。
出口		最終返答の形式と公開可否を見ます。
tool前後		API呼び出しやDB操作を確認します。
人間承認		高権限、課金、本番操作を止めます。

ひとつのguardrailで全部を見るより、失敗点ごとに分けます。

guardrailsは、4層に分けます。

層	止めるもの	代表例
input	agentを走らせる前に止める入力	対象外依頼、危険入力、本人確認不足
output	final outputを返す前に止める出力	schema違反、secret混入、未検証の断言
tool	tool実行の前後で止める副作用	DB更新、外部API、ファイル操作
human review	自動判断しない操作	課金、本番deploy、権限変更、削除

agent-levelだけに寄せない

input/output guardrailsは重要ですが、途中のfunction tool callをすべて守るものではありません。たとえば、入力が安全に見えても、agentが途中で外部APIに危険な引数を渡すことがあります。

副作用がある処理は、toolごとに確認します。実行前に引数と権限を見て、実行後に返却値やログの漏えいを見ます。

自動化しない境界を決める

guardrailで「危険ではなさそう」と判定できても、課金、本番操作、削除、権限変更まで自動化してよいとは限りません。影響が大きい操作はhuman reviewへ回します。

判断基準

止めたい瞬間がagent実行前ならinput、最終返答前ならoutput、tool呼び出し前後ならtool、人間の責任判断が必要ならhuman reviewです。

input guardrailで止めるもの

対象外

製品範囲外、社内規約外の依頼。

危険入力

secret要求、侵害、破壊操作。

コスト

長すぎる入力や巨大調査。

権限

本人確認やroleが必要な依頼。

入口で止められるものは、toolを動かす前に止めます。

input guardrailは、agentを本格的に走らせる前に見る入口です。Python Docsでは、blocking executionにするとguardrail完了前にagentを開始しないため、token消費やtool executionを避けたい場面に向くと説明されています。

止める入力

条件	例
対象外	サービス範囲外、部署外、契約外
危険入力	secret要求、侵害支援、破壊操作
権限不足	本人確認が必要、role不足
高コスト	巨大ファイル解析、長時間調査
曖昧	操作対象や意図が不明

blockingとparallelを分ける

Python Docsでは、input guardrailsにparallel executionとblocking executionがあると説明されています。parallelはlatency面で有利ですが、guardrailが失敗する前にagentがtokenを消費したりtoolを実行し始めたりする可能性があります。

副作用を避けたいなら、blockingに寄せます。単なる分類や軽い品質チェックならparallelでもよい場面があります。

入口で見ない方がよいもの

最終返答のschema、tool返却値のsecret混入、DB更新後の整合性は、入口だけでは見られません。input guardrailに詰め込みすぎず、後段へ分けます。

実務例

「顧客IDを指定して返金して」と来たら、input guardrailで本人確認と権限を確認します。そのうえで返金toolはhuman review付きにします。入口で通ったから返金を自動実行してよい、とはしません。

output guardrailで確認するもの

形式

JSON、schema、必須項目。

漏えい

secret、個人情報、内部情報。

根拠

根拠不足や未検証の断言。

安全

危険手順や過剰な自動化。

output guardrailは最終返答の検査であり、途中のtool実行を止めるものではありません。

output guardrailは、final outputを返す前に見る出口です。Python Docsでは、output guardrailsはfinal outputを出すagentに対して動き、agent完了後に実行されると説明されています。

出口で見るもの

確認項目	例
schema	JSON必須項目、型、enum
漏えい	token、cookie、private key、顧客情報
根拠	未検証なのに断言していないか
安全性	危険な手順をそのまま返していないか
文脈	読者やユーザーの権限に合う内容か

output guardrailの限界

output guardrailは、すでにagentが実行された後の確認です。外部APIを呼んだ後、DBを更新した後、ファイルを書いた後に止めても、副作用は残ります。

だから、output guardrailは「返答を出す前の最後の検査」と考えます。副作用そのものを防ぐ層ではありません。

schemaだけにしない

structured outputやschema validationは大事ですが、schemaが正しくても内容が危険な場合があります。たとえば、summaryが文字列として正しくても、そこにsecretや内部URLが入っていれば止めるべきです。

実務例

サポートagentのfinal outputに、顧客のメールアドレスや内部ticket URLが混ざっていないかを見る。レポートagentのfinal outputに「未確認」を「確認済み」と書いていないかを見る。これはoutput guardrail向きです。

tool guardrailで副作用を抑える

1. 1Input check

   引数、scope、対象IDを確認。

2. 2Execute

   許可されたtoolだけ実行。

3. 3Output check

   返却値にsecretや過剰情報がないか確認。

4. 4Record

   traceや監査ログへ結果を残す。

副作用がある処理は、agentの入口/出口だけでは足りません。

tool guardrailは、function toolを実行する前後に置く確認です。JS Docsでは、input tool guardrailsはtool実行前、output tool guardrailsはtool実行後に動き、allow、rejectContent、throwExceptionのようなbehaviorで扱うと説明されています。

tool前に見るもの

確認	例
引数	ID、path、amount、emailが妥当か
権限	user role、scope、resource owner
対象	sandboxか本番か
制限	rate limit、上限金額、許可path
承認	human reviewが必要か

tool後に見るもの

確認	例
返却値	secretや個人情報を含まないか
結果	成功、失敗、partial success
ログ	過剰なpayloadをtraceへ残さないか
次のstep	agentへ渡してよい情報だけか

副作用toolには必ず境界を置く

次のようなtoolは、agent-level guardrailだけに頼らない方がよいです。

• DB write
• payment/refund
• email送信
• issue/PR作成
• deploy
• file write
• external API mutation
• MCP経由のwrite tool

実務例

createPullRequest toolなら、branch名、対象repo、diff size、secret疑い、CI実行結果をtool前後で確認します。PR本文の品質はoutput guardrailでも見られますが、PRを作成する副作用はtool層で止めます。

handoffでは境界を過信しない

項目	内容	見方
Handoff		専用の移譲経路で動きます。
Tool guardrail		通常のfunction tool向けです。
Hosted tools		同じpipelineとは見ません。
Specialist		移譲先にも役割と制限を置きます。

handoffをfunction toolと同じ守り方で扱わないようにします。

handoffは、specialist agentへ処理を移すための仕組みです。OpenAI Agents SDKのGitHub READMEでも、handoffsはagentのcore conceptとして説明されています。

ただし、JS Docsでは、handoffsはfunction-like toolsとしてmodelへ提示されるものの、通常のfunction-tool pipelineではなくSDKのhandoff pathを通るため、tool guardrailsはhandoff call自体には適用されないと説明されています。

handoffで見ること

項目	見る内容
移譲先	どのspecialistへ渡すか
入力	渡す情報にsecretや過剰情報がないか
権限	移譲先agentのtool権限
返答	最終出力をどのagentが持つか
trace	handoff理由と結果が追えるか

移譲先にも制限を置く

manager agentにguardrailを置いても、specialist agentが別のtoolを持つなら、specialist側の制限も必要です。handoff先がDB write toolを持つなら、そのtoolにもguardrailやhuman reviewを置きます。

hosted toolsも別に見る

JS Docsでは、hosted toolsやbuilt-in execution toolsも、同じtool guardrail pipelineではない注意点が説明されています。built-in toolやhosted toolを使う場合は、そのtoolの提供する設定、権限、監査ログ、sandbox境界を別に確認します。

実務例

「調査agent」から「修正agent」へhandoffする場合、調査agentにはread-only toolだけ、修正agentにはpatch作成toolだけ、deploy toolは持たせない、という分け方にします。handoffは便利ですが、権限の増幅点にもなります。

human reviewへ回す条件

Money

課金、返金、発注、契約。

Production

本番DB、deploy、削除。

Identity

本人確認、権限変更。

Ambiguous

意図や影響範囲が曖昧。

guardrailで判定できても、実行判断は人に戻す場面があります。

human reviewは、guardrailで判定しても自動実行しない境界です。OpenAI Agents SDKの概要Docsでも、approvalsやhuman reviewはSDKで扱う領域として示されています。

人へ回す条件

条件	例
金銭	課金、返金、発注、契約変更
本番	deploy、DB更新、削除、データ移行
権限	role変更、API key発行、招待
外部連絡	顧客メール、SNS投稿、通知
曖昧	影響範囲や意図が不明
高リスク	法務、セキュリティ、個人情報

承認前に出す情報

human reviewへ回すなら、承認者が判断できる情報を出します。

• 何を実行するか
• 対象resource
• 影響範囲
• 実行前の状態
• rollbackできるか
• 実行しない場合の影響
• agentが未確認の点

承認後も記録する

承認者、承認時刻、実行内容、結果、rollback可否を残します。承認は「人間がボタンを押した」だけでは足りません。後から追える形にします。

実務例

payment toolで返金を実行する前に、金額、顧客ID、order ID、理由、過去の返金履歴を表示し、人間が承認した場合だけtoolを実行します。実行後は結果と外部APIのresponse IDを保存します。

tracingで確認する

項目	内容	見方
Generation		model入出力を確認。
Tool call		引数、結果、失敗を確認。
Handoff		移譲先と理由を確認。
Guardrail		通過、拒否、tripwireを確認。

traceは便利ですが、sensitive dataを含む前提で扱います。

OpenAI Agents SDKのtracing Docsでは、run中のLLM generation、tool call、handoff、guardrails、custom eventsを記録し、dashboardでdebug、visualize、monitorできると説明されています。

traceで見るもの

span	見ること
generation	入力、出力、model応答
function tool	tool名、引数、結果、失敗
handoff	移譲先、移譲理由
guardrail	通過、拒否、tripwire
custom event	アプリ固有の判断ログ

sensitive dataを先に決める

tracing Docsでは、generation spanやfunction spanがinput/outputを保存し、そこにsensitive dataが含まれる可能性があると説明されています。trace_include_sensitive_dataや環境変数でcaptureを制御できる説明もあります。

つまり、traceは「あとから見られて便利」ですが、secretや顧客情報を残す経路にもなります。導入前に、traceへ何を含めるか、どの環境で有効にするか、誰が見られるかを決めます。

ZDRや社内ポリシーを確認する

tracing Docsでは、Zero Data Retention policyの組織ではtracingが使えないことも説明されています。企業導入では、SDK設定だけでなく、OpenAI側のデータ保持設定、社内監査要件、ログ保存ルールを確認します。

実務例

開発環境ではtraceを有効にし、function toolの引数からsecretを除外します。本番ではsensitive data captureを無効化し、必要な監査情報はアプリ側の承認済みログへ別途保存します。

最小実装の形

項目	内容	見方
Input		危険入力と対象外を止めます。
Tool		副作用toolに前後チェックを置きます。
Output		最終返答のschemaと漏えいを確認。
Trace config		sensitive data設定を決めます。

最初から複雑なpolicy engineにせず、境界ごとに小さく置きます。

最初は、複雑なpolicy engineを作らず、境界ごとに小さく置きます。

import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";

const createIssue = tool({
  name: "create_issue",
  description: "Create a draft issue after checking scope.",
  parameters: z.object({
    title: z.string().max(120),
    body: z.string().max(4000),
    repo: z.string(),
  }),
  inputGuardrails: [
    async ({ input }) => {
      if (!input.repo.startsWith("example-org/")) {
        return { behavior: "rejectContent", message: "Repository is outside allowed scope." };
      }
      return { behavior: "allow" };
    },
  ],
  execute: async (input) => {
    return { draft: true, title: input.title, repo: input.repo };
  },
});

const agent = new Agent({
  name: "Issue assistant",
  instructions: "Draft issues only. Never publish or mutate production resources.",
  tools: [createIssue],
});

const result = await run(agent, "Draft an issue for the failing login test.");
console.log(result.finalOutput);

この例は最小形です。実務では、input guardrail、output guardrail、human review、trace設定、監査ログを加えます。

実装時のチェックリスト

• user inputを入口で止める条件があるか
• 副作用toolに前後チェックがあるか
• output schemaと漏えいチェックがあるか
• handoff先の権限が分かれているか
• human reviewへ回す条件が明文化されているか
• traceのsensitive data設定を決めたか
• 失敗時のユーザー向けmessageを用意したか

コードより先に決めること

最初に、toolの権限表を作ります。read-only、draft-only、write with approval、never automaticに分けます。SDK実装は、その表に合わせて作る方が安全です。

導入初週の進め方

1. 1日目

   入口で対象外と危険入力を止める。

2. 2日目

   副作用toolだけtool guardrailを置く。

3. 3日目

   最終返答のschemaを確認する。

4. 5日目

   handoff先の役割と制限を分ける。

5. 7日目

   traceを見て失敗条件を1つ足す。

一気に固めず、実際の失敗ログから足します。

guardrailsは、最初から巨大にしません。実際の失敗ログを見ながら、境界ごとに足します。

1日目: inputで対象外と危険入力を止める

サービス範囲外、secret要求、破壊操作、本人確認不足を止めます。副作用toolはまだread-onlyかdraft-onlyにします。

2日目: 副作用toolだけtool guardrailを置く

DB write、外部API mutation、issue作成、file writeなど、副作用があるtoolへ前後チェックを置きます。

3日目: output schemaと漏えいを確認する

final outputのschema、必須項目、secretや個人情報の混入、未検証断言を確認します。

5日目: handoff先の役割と制限を分ける

manager、researcher、writer、executorのようにroleを分け、executorだけがwrite toolを持つ、deploy toolは持たせない、などの権限差を作ります。

7日目: traceを見て1つだけ足す

traceを見て、実際に危なかった失敗を1つだけguardrailへ足します。なんとなく不安だから全部禁止する、という増やし方は避けます。

評価するログ

• guardrailがどこで止まったか
• tool call前に止めるべきものがoutputで止まっていないか
• human reviewへ回すべき操作をagentが自動実行していないか
• traceにsecretや過剰なpayloadが残っていないか

FAQ

全部input?

途中のtool実行は別に守ります。

全部output?

実行後では遅い副作用があります。

Handoff?

移譲先にも制限を置きます。

Trace?

sensitive data設定を先に見ます。

迷ったら、止めたい瞬間がどこかに戻ります。

input guardrailだけで十分ですか

十分ではありません。input guardrailは入口です。途中のtool callやfinal outputは別に見ます。特に副作用toolはtool guardrailやhuman reviewを置きます。

output guardrailだけで安全にできますか

できません。output guardrailはagent完了後に動くため、外部APIやDB更新などの副作用を実行前に止める層ではありません。

tool guardrailはすべてのtoolに効きますか

JS Docsでは、tool guardrailsはtool()で定義したfunction toolsへ適用される説明があります。一方で、handoffs、hosted tools、built-in execution toolsは同じpipelineとして扱わない注意があります。利用するtool種別ごとに確認します。

handoff先にもguardrailは必要ですか

必要です。handoff先agentが別のtoolや権限を持つなら、そのagentやtoolにも制限を置きます。manager agentだけ守っても、specialist側で副作用が出る可能性があります。

tracingは本番で有効にしてよいですか

本番で使うかどうかは、sensitive data、データ保持、アクセス権限、監査要件次第です。tracing Docsでは、input/outputにsensitive dataが含まれる可能性とcapture制御の説明があります。設定を決めずに有効化しない方が安全です。

MCP toolも同じ考え方ですか

基本の考え方は同じです。read-onlyから始め、write toolには引数チェック、権限チェック、human review、監査ログを置きます。MCP導入の権限設計は、MCP仕様・SDK更新時の実務影響チェックやTypeScriptで作る最小MCP Serverも合わせて確認してください。

---

次に読むなら

参照した主な情報源

• OpenAI API Docs: Agents SDK

https://developers.openai.com/api/docs/guides/agents

• OpenAI Agents SDK Python Docs: Guardrails

https://openai.github.io/openai-agents-python/guardrails/

• OpenAI Agents SDK JS Docs: Guardrails

https://openai.github.io/openai-agents-js/guides/guardrails/

• OpenAI Agents SDK Python GitHub: Tracing

https://github.com/openai/openai-agents-python/blob/main/docs/tracing.md

• OpenAI Agents SDK Python GitHub README

https://github.com/openai/openai-agents-python

次に読むなら

更新履歴

1. 2026年5月31日

   OpenAI Agents SDK Docs、Python/JS guardrails Docs、tracing Docs、GitHub READMEを確認して初版を作成しました。

導入時には最新Docsと利用SDKのversionを確認してください。

• 2026年5月31日: OpenAI Agents SDK公式Docs、Python/JS guardrails Docs、tracing Docs、GitHub READMEを確認し、初版を公開しました。