3行まとめ
custom function toolの呼び出しごとに、引数、権限、返却値を確認します。
input/output guardrails、handoff、人間承認は別の層として設計します。
SDKやtool分類は更新されるため、導入時点のDocsとversionを確認します。
「guardrailを入れた」ではなく、どの境界を見ているかで判断します。
- OpenAI Agents SDKのtool guardrailsは、custom function toolの実行前後を確認するための層です。agent-levelのinput/output guardrails、handoff、built-in tools、人間承認をまとめて代替するものではありません。
- 実務では、function tool、hosted tools、built-in execution tools、MCP、agents as toolsを同じ「tool」として扱わず、止める場所、ログ、承認条件を別々に決めます。
- Xで見えるguardrailsやagent安全性への関心は需要シグナルとして参考にしつつ、本文の根拠は2026年6月3日に確認したOpenAI公式Docs、公式GitHub、npm/PyPIの確認値に寄せています。
この記事でわかること
input、output、function tool、人間承認のどこで止めるかを決めます。
function tool、hosted tool、builtin execution tool、MCPを同じ前提で扱わないようにします。
移譲先agentへ渡す情報と、渡さない情報を分けます。
本番変更、削除、課金、権限変更などを人間へ戻す条件にします。
事故後の説明と運用改善に必要な記録だけを残します。
目的は、toolをどこで止めるべきかをチームで会話できる状態にすることです。
この記事では、OpenAI Agents SDKでtool guardrailsを入れる前に、設計レビューで決めるべき境界を整理します。すでに全体像を押さえたい場合は、公開済みのOpenAI Agents SDKのguardrailsを置く場所から読むとつながりやすいです。
- input/output guardrailsとtool guardrailsの違い
- function toolの実行前に見る項目
- function toolの実行後に見る項目
- built-in execution toolsやhosted toolsを別枠で扱う理由
- handoff時に渡す情報と渡さない情報
- 人間承認に出すべき操作と、承認画面に必要な情報
- tracingを安全策ではなく監査と改善の材料として使う考え方
扱わないものも明確にします。この記事はSDKの完全な実装チュートリアルではありません。攻撃手順、回避手順、各社法務判断、料金比較、特定プロダクトの導入可否の断定は扱いません。目的は、PRレビューや設計レビューで「このtoolはどこで止めるべきか」を会話できる状態にすることです。
前提知識: guardrailは置き場所で意味が変わる
- 1ユーザー入力
agent実行前に、対象外依頼、権限不足、危険な依頼を確認します。
- 2function tool
tool実行前後に、対象、操作種別、権限、返却値を確認します。
- 3最終出力
顧客送信や公開文面の前に、schema違反やsecret混入を確認します。
- 4handoff
移譲先agentへ渡す履歴、権限、tool listを別に確認します。
- 5人間承認
自動化しない判断を、差分、影響、rollback条件と一緒に確認します。
名前が同じでも、止める対象と責任境界は同じではありません。
OpenAI Agents SDKのguardrails docsでは、agent-levelのinput guardrails、output guardrails、function toolに対するtool guardrailsが分けて説明されています。重要なのは、どれも「guardrail」という名前でも、動くタイミングが違うことです。
公式Docs上の分類を先に分ける
根拠
input guardrailは、最初のユーザー入力を見ます。output guardrailは、最終出力を見ます。tool guardrailsは、function toolの呼び出しごとに、実行前と実行後を見ます。OpenAI Agents SDKのJS/Python docsでは、handoffは通常のfunction tool pipelineとは別経路で扱われ、hosted toolsやbuilt-in execution toolsも同じtool guardrail pipelineを使う前提ではないと説明されています。
よくある誤解を潰す
注意点
この差を曖昧にすると、次のような誤解が起きます。
| 誤解 | 起きる問題 |
|---|---|
| guardrailを入れたのでtool実行は全部安全 | 対象外のtool種別やhandoff後のagentを見落とす |
| schemaがあるので権限チェックは不要 | 形は合っているが、実行してはいけない操作が通る |
| tracingがあるので事故を防げる | traceは事後確認に強いが、実行前の承認を代替しない |
| handoffはtoolと同じように止められる | 移譲先agentのinstructions、tools、権限が別管理になる |
つまり、最初に決めるべきことは「どの機能を使うか」ではなく、「どの瞬間に何を止めたいか」です。
結果: tool guardrailsだけで守る設計にしない
tool guardrailsはfunction toolの一部を守る層で、他の境界を置き換えません。
実務での結論はシンプルです。tool guardrailsは必要ですが、万能ではありません。特に副作用のあるagentアプリでは、少なくとも4つの境界に分けます。
| 境界 | 見る対象 | 代表例 | 人間へ戻す条件 |
|---|---|---|---|
| input | agent実行前の依頼 | 対象外依頼、権限不足、危険な依頼 | 本人確認や責任者判断が必要 |
| output | 最終返答 | schema違反、secret混入、未検証の断定 | 顧客送信、公開文面、法務確認が必要 |
| function tool | tool実行前後 | DB更新、外部API、ファイル操作 | 本番変更、削除、課金、権限変更 |
| human approval | 自動化しない判断 | deploy、返金、ユーザー停止、credential変更 | 承認者が影響とrollbackを確認する |
function toolのtool guardrailsは、ここでいう3列目の一部を守ります。agent-level input/output guardrailsや人間承認の代わりに使うものではありません。
input/output guardrailsで見るもの
評価基準
input guardrailでは、agentを走らせる前に止められるものを見ます。対象外の依頼、利用者のrole不足、危険な依頼、巨大すぎる入力、外部APIコストが読めない依頼は、toolを呼ぶ前に止めたほうが安いです。
output guardrailでは、最終返答を返す前に見ます。schema違反、個人情報やcredentialの混入、未検証の断定、社外送信してはいけない文面などが対象です。
ここで注意したいのは、input/output guardrailsは途中の全tool callを細かく見る層ではないことです。途中の副作用を止めたいなら、function tool側のguardrail、承認、実行環境の制限を別に置きます。
tool guardrailsで見るもの
条件
tool guardrailsでは、function toolの実行前後を分けます。実行前は、引数、操作対象、認証状態、scope、dry-run可否、rate limit、冪等性を見ます。実行後は、返却値、エラー、ログ、外部APIの応答、モデルに戻してよい情報を見ます。
たとえば、顧客管理システムのupdateCustomerPlanというfunction toolをagentに渡す場合、入力schemaだけでは不十分です。customerIdの形が正しくても、その顧客を操作する権限があるか、プラン変更が課金を伴うか、変更後に通知が飛ぶか、rollbackできるかは別の判断です。
人間承認へ戻すもの
注意点
課金、本番deploy、データ削除、権限変更、外部送信、顧客に影響する処理は、モデルが「安全そう」と判定しても自動許可しない方がよい場面が多いです。人間承認は、guardrailの最後の分岐ではなく、責任者が見るべき操作を自動化の外へ出す運用です。
この考え方は、MCPやAIコーディングエージェントにもそのまま効きます。MCPのTools、Resources、Promptsの違いから整理したい場合は、MCPとは何かも合わせて見ると、外部toolの権限設計とつなげやすくなります。
function toolは実行前と実行後を分けて守る
- 1操作対象
customer、repo、issue、file、orderなどが正しいかを確認します。
- 2操作種別
read、create、update、delete、sendのどれかを明確にします。
- 3権限とscope
実行者、agent run ID、API token、MCP serverの権限を追える状態にします。
- 4dry-runと冪等性
本番変更前に確認でき、retryで二重実行されない設計にします。
- 5tool実行
承認条件にかからない操作だけを実行します。
- 6返却値の最小化
モデルに返してよい情報だけを残し、内部URLやtokenを削ります。
- 7ログ分離
原因調査用ログとモデル向けメッセージを分けます。
schemaは型を制約しますが、実行してよいかまでは決めません。
function toolを設計するときは、1つのチェックで全部を済ませない方が安全です。実行前と実行後で、見るべきリスクが違います。
実行前は引数と権限を見る
確認項目
実行前に見るべき項目は、最低でも次の7つです。
| 項目 | 確認すること |
|---|---|
| 操作対象 | customer、repo、issue、file、orderなどが正しいか |
| 操作種別 | read、create、update、delete、sendのどれか |
| 実行者 | user、service account、agent run IDが追えるか |
| scope | API tokenやMCP serverの権限が過剰でないか |
| dry-run | 本番変更前に確認できるか |
| 冪等性 | retryで二重実行されないか |
| 承認条件 | どの条件で人間へ戻すか |
入力schemaは、この表の一部しか見ません。型、必須項目、列挙値を制約できても、実行してよいかは別です。
実行後は返却値とログを見る
注意点
toolの結果をそのままモデルへ戻すと、別の事故が起きます。外部APIのエラー詳細、内部URL、stack trace、顧客情報、token、署名付きURL、契約情報が混ざることがあります。
実行後のguardrailでは、少なくとも次を確認します。
- モデルに返してよい最小情報だけに削る
- secret、個人情報、内部ID、署名付きURLを除去する
- エラーは原因調査用ログとモデル向けメッセージに分ける
- 実行結果が期待した対象に対して起きたかを確認する
- 成功、拒否、承認待ち、失敗を同じ型で返す
実務では、toolの戻り値を「人間が読むログ」と「モデルが次の判断に使う情報」に分けるだけで事故が減ります。モデルに全部見せる必要はありません。
schemaを安全策と混同しない
根拠
OpenAI Agents SDKのtools docsでは、function toolsはlocal functionをJSON schemaでwrapしてモデルに呼ばせるものとして説明されています。これは強力ですが、schemaは権限そのものではありません。
たとえば、amountがnumberで、currencyがJPYで、userIdがstringでも、その返金を実行してよいとは限りません。返金理由、注文状態、承認者、金額閾値、過去の返金履歴、社内規程を見る必要があります。
schemaは「形をそろえる層」です。権限、責任、監査、rollbackは別に置きます。
built-in execution toolsとhosted toolsは別枠で扱う
tool guardrailsが効く前提でまとめず、tool種別ごとに外側の制御も決めます。
OpenAI Agents SDKのJS tools docsでは、toolsが複数カテゴリに分かれています。Hosted OpenAI tools、built-in execution tools、function tools、agents as tools、MCP servers、sandbox capabilities、experimentalなCodex toolなどです。
このうち、tool guardrailsの説明で中心になるのはfunction toolsです。hosted toolsやbuilt-in execution toolsまで同じ前提で「tool guardrailが効く」とみなすのは危険です。
custom function toolと同じ前提にしない
根拠
hosted toolsは、web search、file search、code interpreter、image generation、tool searchなど、OpenAI側の仕組みと結びつくtoolです。built-in execution toolsは、computer、shell、apply patchなど、モデルの応答外で実行される処理です。
JS guardrails docsでは、hosted toolsやbuilt-in execution toolsがfunction toolのguardrail pipelineとは別扱いになる注意が示されています。Python docsでも、Hosted toolsやComputerTool、ShellTool、ApplyPatchTool、LocalShellToolなどは通常のfunction tool guardrailsの対象として扱わない説明があります。
したがって、ここでは外側の対策を足します。
| tool種別 | 主なリスク | 外側に置く対策 |
|---|---|---|
| hosted web search | 未信頼Web、引用不能な情報、外部通信 | allowed domains、根拠確認、出典ログ |
| file search | 機密文書、古いindex、権限差 | index単位のACL、retrieval log、redaction |
| shell | 破壊的コマンド、外部通信、secret参照 | sandbox、allowlist、approval、作業dir制限 |
| apply patch | 意図しない編集、広範囲変更 | diff preview、review、rollback、test |
| MCP server | 外部サービス操作、権限過多 | read-only開始、server単位のscope、監査ログ |
外部通信をAI agentへ許可する設計は、単独で考えるよりもnetwork allowlistやMCPの扱いと合わせる方が現実的です。Codex文脈では、Codexにインターネットアクセスを許可する前にで整理した境界が参考になります。
shellToolのlocal modeとhosted container mode
条件
JS tools docsでは、shellTool()にはlocal modeとhosted container modeがあると説明されています。local modeではneedsApprovalやonApprovalを使える一方、hosted container modeでは実行がhosted container環境で行われるため、同じ引数を受け付けない説明があります。
この違いは実務上かなり大きいです。localでapproval callbackを設計したつもりでも、hosted containerへ移したときに同じ承認経路で止まるとは限りません。実装前に、どの実行環境で、どのapproval hookが使えるかを公式Docsで確認します。
使わない判断も選択肢にする
危険なtoolは「どう守って使うか」だけでなく、「そもそもagentに渡さない」判断もあります。特に本番DBの直接変更、社外送信、credential更新、ユーザー停止、支払い実行は、最初からagentのtool listに入れず、人間の管理画面や既存workflowへ戻す方が安全なことがあります。
handoffは移譲先agentの権限まで見る
- 1元agent
移譲理由、ユーザー意図、必要な履歴を明確にします。
- 2input filter
移譲先に不要なtool結果、内部メモ、失敗ログ、個人情報を渡さないようにします。
- 3移譲先agent
instructions、tools、出力責務を別の部品としてレビューします。
- 4handoff後のtool list
移譲先agentが使えるtoolの副作用、認証、承認条件を確認します。
- 5approvalとtrace
強い権限を持つ移譲先agentほど、承認とtraceの要件を強めます。
handoffは便利な移譲であり、guardrail済みの単なるtool callとして扱いません。
handoffは、専門agentへ処理を移すための仕組みです。OpenAI Agents SDKのhandoffs docsでは、handoffはLLMにtoolとして提示されるものの、通常のfunction tool pipelineとは別のhandoff pathで扱われる説明があります。
ここで大事なのは、handoffを「別のtool call」として雑に扱わないことです。移譲先agentは、別のinstructions、別のtools、別の出力責務を持つことがあります。
handoff前に渡す情報を絞る
確認項目
handoffs docsでは、handoff先へ渡す入力をinputFilterで調整できる説明があります。デフォルトで会話履歴を丸ごと渡す設計にすると、移譲先agentに不要なtool結果、内部メモ、失敗ログ、個人情報が流れる可能性があります。
handoff前に確認する項目は次の通りです。
| 項目 | 見ること |
|---|---|
| input history | 移譲先に必要な履歴だけか |
| tool result | secretや内部エラーが混ざっていないか |
| user intent | 移譲理由が明確か |
| authority | 移譲先agentの権限が過剰でないか |
| final output | 最終責任を持つagentがどれか |
handoff後のtool listを別にレビューする
注意点
移譲先agentに、元agentより強いtoolsを持たせるなら、handoffは権限昇格の入口になります。たとえば、FAQ agentからRefund agentへhandoffした結果、返金APIや顧客管理APIに触れるなら、元のinput guardrailだけでは足りません。
移譲先agentごとに、tools、guardrails、approval、trace、ログ保存をレビューします。handoffが多いworkflowほど、agent単位の権限表が必要になります。
agents as toolsとも分ける
Agents SDKには、agentをtoolとして使う構成もあります。これはhandoffと似て見えますが、会話の主導権や最終出力の責務が違います。specialistに処理を完全に移すのか、元agentの裏側で補助toolとして呼ぶのかで、guardrailとログの置き方が変わります。
実務では、handoff、agents as tools、MCP tool、function toolを同じ表に並べ、どれが最終出力を持つのか、どれが副作用を持つのかを明記します。
人間承認は「何を見て許可したか」まで設計する
repo、issue、customer、order、file、environmentを明示します。
update、delete、send、deploy、refundなどを区別します。
変更前後、対象件数、dry-run結果を確認できるようにします。
顧客通知、課金、外部送信、権限変更への影響を示します。
入力、参照したdocs、tool結果、実行者、agent run IDを追えるようにします。
戻し方、期限、担当者を承認前に確認します。
承認待ちをいつまで保持するかを決めます。
guardrailは検査で、承認は責任判断です。両方の役割を混ぜないようにします。
人間承認は、単に「Approveボタンを出す」ことではありません。承認者が、操作対象、差分、影響、コスト、rollback条件を見て判断できる形にする必要があります。
承認画面に必要な情報
承認UIやPRコメントに最低限出したい情報は次の通りです。
| 項目 | 例 |
|---|---|
| 操作対象 | repo、issue、customer、order、file、environment |
| 操作種別 | update、delete、send、deploy、refund |
| 差分 | 変更前後、対象件数、dry-run結果 |
| 影響 | 顧客通知、課金、外部送信、権限変更 |
| 実行者 | user、agent run ID、service account |
| 根拠 | 入力、参照したdocs、tool結果 |
| rollback | 戻し方、期限、担当者 |
| 期限 | いつまで承認待ちにするか |
この情報が出せない操作は、自動化の前に既存業務フローを整える必要があります。
承認とguardrailを混ぜない
guardrailは検査です。承認は責任判断です。検査がPASSでも、承認が必要な操作はあります。逆に承認者が「今回は実行する」と判断しても、実装側の禁止条件を超えてはいけない操作もあります。
たとえば、本番DBの大量削除は、承認者がいてもagentから直接実行しないルールにできます。この場合、guardrailで止める以前に、toolをagentへ渡さない設計が正解です。
承認付きworkflowは状態管理も必要
人間承認を挟むと、agent runは一度止まります。承認後にどの状態から再開するのか、同じtoolを二重実行しないか、期限切れの承認をどう扱うかを決めます。
LangGraphやMastraなどの承認付きworkflowの比較に進むなら、LangGraphとMastraで同じ承認付きワークフローを作るが次の論点になります。OpenAI Agents SDKだけでなく、workflow engine側の状態保存も含めて判断するためです。
tracingは止める機能ではなく、説明する材料にする
tracingは実行前に止める機能ではなく、説明と改善の材料です。
OpenAI Agents SDKのtracing docsでは、agent run中のLLM generation、tool calls、handoffs、guardrails、custom eventsなどを記録し、debug、visualize、monitorに使えると説明されています。
これは非常に有用ですが、tracingは実行前に止める機能ではありません。事故後に「どのtoolが、どの引数で、どのagentから呼ばれたか」を追う材料です。
traceに残すもの
traceに残したいものは、再現と監査に必要な情報です。
- agent run ID
- user IDまたはrole
- tool名
- tool引数の安全な要約
- approval ID
- handoff先agent
- guardrailの判定結果
- 実行結果の分類
一方で、secret、access token、顧客の詳細な個人情報、内部ログ全文、契約情報、署名付きURLはそのまま残すべきではありません。
traceから改善する
traceを使うと、どのtoolで承認待ちが多いか、どのguardrailが過剰に止めているか、handoff後に失敗が増えているかを見られます。これは運用改善に向いています。
ただし、traceを見られる人の権限も設計が必要です。traceが社内情報の集約地点になるなら、ログ基盤と同じようにアクセス制御、保存期間、削除、監査を決めます。
失敗点・ハマりどころ
function tool、hosted tool、builtin execution tool、MCP toolは実行場所と対象範囲が違います。
移譲先agentのtools、guardrails、approval、traceを別にレビューします。
対象、差分、影響、rollbackがない承認は、判断の責任を支えられません。
事故調査のためのtraceが、secretや個人情報の漏えい元にならないようにします。
tool listを1行ずつ棚卸しし、副作用、認証、承認、ログ、rollbackを書ける状態にします。
OpenAI Agents SDKに限らず、agent tool設計でよく起きる失敗は、機能名を見て安心してしまうことです。
toolという名前で全部まとめる
function tool、hosted tool、built-in execution tool、MCP tool、agent as toolは、モデルから見ると「呼べるもの」に見えます。しかし、実行場所、承認方法、ログ、guardrail対象が違います。
設計レビューでは、tool listを1行ずつ棚卸しします。名前、種別、副作用、認証、承認、ログ、rollbackを書けないtoolは、まだagentへ渡さない方がよいです。
handoff後のagentを信用しすぎる
handoffは便利ですが、責任境界が見えにくくなります。元agentの入力guardrailが通ったからといって、移譲先agentのtool実行まで安全になるわけではありません。
handoff先agentは、別のアプリケーション部品としてレビューします。特に強い権限を持つspecialist agentは、人間承認とtraceの要件を強めます。
承認UIに差分がない
承認UIで「実行しますか」だけを見せても、承認者は判断できません。対象、差分、影響、rollbackがない承認は、実務上の責任判断になりません。
承認UIを作る前に、dry-runとpreviewを先に作ります。previewできない操作は、agentによる自動提案だけにとどめます。
traceへ情報を残しすぎる
traceは便利なぶん、情報が集まりやすいです。toolの生レスポンスやエラーをそのまま入れると、ログ側にcredentialや顧客情報が残ります。
traceに入れるのは、再現と監査に必要な最小情報です。詳細ログはアクセス制御された別基盤へ分け、モデルに戻す情報も絞ります。
実務で使うなら
- read-only function tool
Issue取得、ドキュメント検索、feature flag一覧などから始めます。
- 実行前guardrail
対象ID、利用者role、scope、承認条件を確認します。
- 実行後guardrail
返却情報を削り、モデルに見せる情報とログを分けます。
- write系tool
create、update、delete、sendの順に、dry-run、preview、approval、rollbackを揃えて増やします。
- PRのtoolレビュー表
tool名、種別、副作用、認証、承認、ログ、rollbackをレビューできる形にします。
- 更新時の確認場所
SDK release notes、Docs、tool list、MCP server scope、承認ログを固定して見ます。
readonlyから始めると、guardrail、承認、traceの責任境界を確認しやすくなります。
導入順は、小さく始めるのが安全です。最初からshell、MCP、本番API、handoff、承認、traceを全部入れると、どこで事故が起きたのか追いづらくなります。
read-only function toolから始める
最初はread-onlyのfunction toolを1つだけ渡します。たとえば、Issueの取得、ドキュメント検索、feature flag一覧の取得などです。実行前guardrailでは対象IDと権限を確認し、実行後guardrailでは返却情報を削ります。
その後、create、update、delete、sendの順に権限を増やします。write系を入れる前に、dry-run、preview、approval、rollback、traceを揃えます。
toolレビュー表をPRに入れる
agentに新しいtoolを渡すPRでは、次の表を本文に入れるとレビューしやすくなります。
| 項目 | 記入例 |
|---|---|
| tool名 | getIssueSummary |
| 種別 | function tool、MCP、hosted、built-in |
| 副作用 | read-only、create、update、delete、send |
| 認証 | user token、service account、MCP server scope |
| 実行前確認 | role、対象ID、rate limit |
| 実行後確認 | secret除去、要約化、エラー整形 |
| 承認条件 | 本番変更、外部送信、件数閾値 |
| rollback | 不要、手動、API、migration revert |
| trace | tool名、run ID、判定、要約だけ |
この表を埋められないtoolは、設計がまだ早いと判断できます。
更新時に見る場所を固定する
SDKは更新されます。この記事を書いた2026年6月3日時点では、npm view @openai/agents versionで0.11.6、pip index openai-agentsでlatest 0.17.4を確認しました。実装時には、使う言語のSDK、guardrails docs、tools docs、handoffs docs、tracing docsを再確認してください。
特に見るべき差分は、tool guardrailsの対象範囲、hosted/built-in toolsのapproval、handoffの入力filter、sandbox対応、traceの保存設定です。
セキュリティ・コスト注意
認証はアプリケーション側、MCP server側、実行環境側で管理します。
外部APIのエラー、HTTP header、署名付きURL、debug logをモデルへ返す前に削ります。
allowed domains、network policy、file mount、secret参照範囲を明記します。
sandbox、shell、web search、MCP serverがどこへ通信できるかを確認します。
モデル判定をそのまま監査ログにせず、説明できる記録に整えます。
token、tool use、hosted execution、外部API、sandbox利用を計測します。
セキュリティ、監査、コストは同時に見るものですが、権限事故を先に潰します。
agent tool設計では、コストより先に権限事故を考えます。もちろんtoken、tool use、hosted execution、外部API、sandbox利用にはコストがあります。しかし、最初に壊れるのは請求額よりも、credential、本番データ、顧客影響、監査不能な実行です。
credentialをtoolへ渡さない
agentやtool引数にcredentialを直接渡さない方針を基本にします。必要な認証は、アプリケーション側、MCP server側、実行環境側で管理し、モデルにtokenを見せません。
toolの返却値にもcredentialが混ざる可能性があります。外部APIのエラー、HTTP header、署名付きURL、debug logは、モデルへ返す前に削ります。
hosted実行と外部通信を許可制にする
hosted toolsやsandbox、shell、web search、MCP serverを使う場合、外部通信を許可制にします。allowed domains、network policy、file mount、environment variables、secret参照範囲を明記します。
外部通信をすべて禁止する必要はありません。ただし、どこへ通信できるか、何を送ってよいか、誰が許可したかをログに残します。
モデル判定を監査ログにしない
「モデルが安全と判断した」は監査ログではありません。監査ログには、誰が、いつ、何を、どの権限で、どの差分として、どの承認IDで実行したかを残します。
モデルのreasoningや内部判断をそのまま監査証跡にするのではなく、アプリケーション側で構造化した実行記録を残します。
導入しない方がよいケース
対象toolが何を変更するか説明できない場合は、agentへ渡さない方が安全です。
本番操作と検証操作が同じcredentialで動く状態は見直します。
確認や戻し方がないwrite系操作は、自動化の前に手順を作ります。
対象、変更前後、影響が見えない承認は判断材料が足りません。
ログやtraceが漏えい元になる場合は、記録方針から直します。
移譲先agentのtool listや権限を確認できない場合は、handoff設計を止めます。
対象versionと公式Docsを固定しないまま安全設計を判断しないようにします。
止まる場所を増やすだけでは、責任境界は明確になりません。
次の条件に当てはまる場合、tool guardrailsの実装より先に、業務フローや権限設計を見直した方がよいです。
設計が説明できないtool
確認項目
- 対象toolの副作用を説明できない
- 本番操作と検証操作が同じcredentialで動く
- handoff先agentのtool listを把握していない
- SDKの対象versionを固定していない
承認とrollbackが揃っていない操作
注意点
- dry-runやpreviewがない
- rollback手順がない
- 承認者が差分を見られない
- traceやログにsecretが混ざる
この状態でguardrailだけを足すと、止まる場所は増えても、責任境界は曖昧なままです。
FAQ
不要にはなりません。課金、本番deploy、削除、権限変更は人間が差分と影響を確認します。
同じ前提では見ません。使うSDK versionの公式Docsで対象範囲を確認します。
handoff前に渡す情報を絞り、移譲先agentのtoolsとapprovalを別にレビューします。
十分とは限りません。tracingは説明材料であり、実行前の承認や制限とは別です。
同じ観点で見ますが、server scope、認証、外部通信、返却値を別に確認します。
迷ったら、どの層で止める話かを先に分けると判断しやすくなります。
tool guardrailsを入れればhuman approvalは不要ですか
不要にはなりません。tool guardrailsはfunction toolの実行前後を確認する層です。課金、本番deploy、削除、権限変更、顧客影響のある操作は、人間が差分と影響を確認する設計にします。
hosted toolsやbuilt-in toolsにも同じtool guardrailsを置けますか
同じ前提では見ない方が安全です。OpenAI Agents SDKのguardrails docsでは、tool guardrailsはfunction toolsを中心に説明され、hosted toolsやbuilt-in execution toolsは同じpipelineとして扱わない注意が示されています。使うSDK versionの公式Docsで対象範囲を確認してください。
handoffはtool callとしてguardrailできますか
handoffはLLMにはtoolのように提示されますが、通常のfunction tool pipelineとは別のhandoff pathで扱われます。handoff前に渡す情報を絞り、handoff先agentのtools、guardrails、approval、traceを別にレビューします。
tracingを有効にしていれば事故調査は十分ですか
十分とは限りません。tracingはtool calls、handoffs、guardrailsなどを追う材料になりますが、実行前の承認やsecret対策を代替しません。traceに残す情報も、最小化とアクセス制御が必要です。
MCP serverを使う場合も同じ考え方ですか
大枠は同じです。MCP serverのtoolsも、副作用、scope、認証、承認、ログを分けてレビューします。ただしMCPにはHost、Client、Server、transport、authorizationの設計があるため、MCP側の仕様確認も必要です。
関連資料と導線
OpenAI Agents SDK、guardrails、MCP、workflow engineの変更を継続的に追います。
APIキー、非公開リポジトリ、承認フロー、社内規程を含めて棚卸しします。
承認UIやログ基盤を作る前に、toolの副作用、認証、承認、rollbackを1つ埋めます。
まずは自分のチームでtool権限をレビューできる状態にします。
SDKやMCP、agent workflowの更新は速いので、継続的に追うならニュースレターで更新通知を受け取れるようにしておくと便利です。法人導入でAPIキー、非公開リポジトリ、承認フローを含めて棚卸しする場合は、記事末尾のお問い合わせから相談できます。
この記事の主目的は、相談へ誘導することではなく、まず自分のチームでtool権限をレビューできる状態にすることです。承認UIやログ基盤を作る前に、上のtoolレビュー表を1つ埋めてみてください。
次に読むなら
参照した主な情報源
- OpenAI Agents SDK JS Guardrails docs: https://openai.github.io/openai-agents-js/guides/guardrails/
- OpenAI Agents SDK Python Guardrails docs: https://openai.github.io/openai-agents-python/guardrails/
- OpenAI Agents SDK JS Tools docs: https://openai.github.io/openai-agents-js/guides/tools/
- OpenAI Agents SDK JS Handoffs docs: https://openai.github.io/openai-agents-js/guides/handoffs/
- OpenAI Agents SDK JS Tracing docs: https://openai.github.io/openai-agents-js/guides/tracing/
- OpenAI blog: The next evolution of the Agents SDK: https://openai.com/index/the-next-evolution-of-the-agents-sdk
- openai-agents-js GitHub repository: https://github.com/openai/openai-agents-js
- openai-agents-python GitHub repository: https://github.com/openai/openai-agents-python
更新履歴
- 2026-06-03 公式Docs確認
OpenAI Agents SDK JS/Python guardrails、tools、handoffs、tracing docs、公式GitHubを確認しました。
- 2026-06-03 package version確認
@openai/agentsはnpm latest 0.11.6、openai-agentsはPyPI latest 0.17.4を確認しました。
- 2026-06-03 初回公開
tool guardrailsの対象範囲、builtin/hosted tools、handoff、人間承認を分けて記載しました。
- 2026-06-03 X公開ページ方針
個別投稿や反応数を本文根拠にせず、技術的根拠は公式一次情報に寄せました。
履歴は、後からSDKの変更点と記事の前提を照合するために使います。
| 日付 | 確認内容 | 記事への影響 |
|---|---|---|
| 2026-06-03 | OpenAI Agents SDK JS/Python guardrails、tools、handoffs、tracing docs、公式GitHubを確認。@openai/agentsはnpm latest 0.11.6、openai-agentsはPyPI latest 0.17.4を確認。 | 初回公開。tool guardrailsの対象範囲、built-in/hosted tools、handoff、人間承認を分けて記載。 |
| 2026-06-03 | 指定Xアカウントの公開ページは取得が安定せず、個別投稿や反応数を本文根拠にしない方針にした。 | 需要シグナルはテーマ選定の補助に限定し、技術的根拠は公式一次情報に限定。 |