自動チェックにはガードレールを使い、承認の判断には人によるレビューを使います。この 2 つを組み合わせて、実行を続ける条件、一時停止する条件、終了する条件を定めます。
- ガードレールは、入力、出力、またはツールの動作を自動的に検証します。
- 人によるレビューでは、実行を一時停止し、慎重な扱いが必要な操作を人またはポリシーが承認もしくは却下できるようにします。
用途に応じた制御方法
| 用途 | 最初に使う制御方法 |
|---|---|
| メインモデルを実行する前に、許可されていないユーザーリクエストをブロックする | 入力ガードレール |
| 最終出力をシステムの外に出す前に、内容を検証するか、開示できない部分を伏せる | 出力ガードレール |
| 関数ツールの呼び出し前に引数を確認するか、呼び出し後に結果を確認する | ツールガードレール |
| キャンセル、編集、シェルコマンドの実行、慎重な扱いが必要な MCP 操作などの副作用が生じる前に一時停止する | 人による承認 |
ブロッキング方式のガードレールの追加
ワークフローの中で、コストの高い処理や副作用を伴う処理を始める前に短時間で検証を済ませたい場合は、入力ガードレールを使います。
import { Agent, InputGuardrailTripwireTriggered, run } from "@openai/agents";
import { z } from "zod";
const guardrailAgent = new Agent({
name: "Homework check",
instructions: "Detect whether the user is asking for math homework help.",
outputType: z.object({
isMathHomework: z.boolean(),
reasoning: z.string(),
}),
});
const agent = new Agent({
name: "Customer support",
instructions: "Help customers with support questions.",
inputGuardrails: [
{
name: "Math homework guardrail",
runInParallel: false,
async execute({ input, context }) {
const result = await run(guardrailAgent, input, { context });
return {
outputInfo: result.finalOutput,
tripwireTriggered: result.finalOutput?.isMathHomework === true,
};
},
},
],
});
try {
await run(agent, "Can you solve 2x + 3 = 11 for me?");
} catch (error) {
if (error instanceof InputGuardrailTripwireTriggered) {
console.log("Guardrail blocked the request.");
} else {
throw error;
}
}メインエージェントを起動するコストやリスクが高すぎる場合は、ブロッキング方式で実行します。検証結果が出る前に処理を始めてもレイテンシを抑えたい場合は、ガードレールを並列で実行します。
人によるレビューのための一時停止
ツール呼び出しの承認は、人が実行の可否を判断するための仕組みです。モデルは操作が必要だと判断できますが、その操作を承認または却下するまで実行は一時停止します。
import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";
const cancelOrder = tool({
name: "cancel_order",
description: "Cancel a customer order.",
parameters: z.object({ orderId: z.number() }),
needsApproval: true,
async execute({ orderId }) {
return `Cancelled order ${orderId}`;
},
});
const agent = new Agent({
name: "Support agent",
instructions: "Use cancel_order to handle cancellation requests.",
tools: [cancelOrder],
});
let result = await run(agent, "Cancel order 123.");
if (result.interruptions?.length) {
const state = result.state;
for (const interruption of result.interruptions) {
console.log(`Approval required: ${interruption.name}`);
state.approve(interruption);
}
result = await run(agent, state);
}
console.log(result.finalOutput);承認が必要なツールが、ハンドオフの後やネストされた agent.asTool()
承認のライフサイクル
ツール呼び出しにレビューが必要な場合、SDK は毎回同じ手順で処理します。
- ツールを実行せず、承認待ちによる中断を実行記録に残します。
- 実行結果には
interruptionsと、実行を再開するためのstateが含まれます。 - アプリケーションで保留中の項目を承認または却下します。
- 新しいユーザーターンを始めずに、
stateから同じ実行を再開します。
レビューに時間がかかりそうな場合は、state をシリアライズして保存し、後で再開します。この場合も同じ実行が続きます。
ワークフロー内でのガードレールの適用範囲
エージェントレベルのガードレールが動作する箇所は限られています。
- 入力ガードレールは、一連のエージェントのうち最初のエージェントでのみ動作します。
- 出力ガードレールは、最終出力を生成するエージェントでのみ動作します。
- ツールガードレールは、そのガードレールを設定した関数ツールで動作します。
マネージャー型のワークフローですべてのカスタムツール呼び出しをチェックする必要がある場合は、エージェントレベルの入力ガードレールや出力ガードレールだけに頼らず、副作用を生じさせるツールの呼び出し箇所に検証処理を置きます。
サイバーセキュリティ操作の実行前レビュー
許可を受けたサイバーセキュリティのワークフローでは、慎重な扱いが必要なツール呼び出しを一件ずつ実行前に評価します。ツールガードレールと承認待ちによる中断を使い、副作用が生じる箇所で、書面で定めた作業範囲を超える操作を防ぎます。
- 提案された対象、操作、ツールの引数、呼び出し元の ID、作業時間帯を、承認済みの作業範囲と照合します。
- 独立したポリシー判定コンポーネントまたはレビュー担当者に、提案された操作の正確な内容と、その評価に必要なコンテキストだけを渡します。
- 範囲外のホストへのアクセス、認証情報の窃取、侵入の永続化、データの不正な持ち出し、破壊的な変更、本番環境へのアクセス、ポリシーの回避を試みる操作を拒否します。
- 判断が難しい操作やリスクの高い操作は保留し、人による明示的な承認を得てからツールを実行します。
- ファイルシステム、ネットワーク、ID、プロジェクトごとに独立した制限を適用し、判断と実行結果を記録します。レビューがタイムアウトした場合や利用できなくなった場合は、操作を拒否します。
Responses API や Agents SDK を使うアプリケーションには、Codex の自動レビューは自動的には引き継がれません。独自のハーネスにレビューとポリシー適用の仕組みを組み込んでください。オープンソースの Codex レビューポリシーに、その一例があります。承認済みのモデルアクセスについてはモデルと信頼済みアクセスを、安全に作業するための設定については推奨構成を参照してください。
ストリーミングと後から行うレビューに共通の状態モデル
ストリーミングでも承認の仕組みは同じです。ストリーミング中に実行が一時停止した場合は、停止処理が完了するまで待ち、interruptions を確認します。保留中の項目を承認または却下してから、同じ state から実行を再開します。後でレビューする場合は、シリアライズした状態を保存し、判断が下された時点で同じ実行を再開します。
次のステップ
各制御がどこで働くかを確認したら、関連するランタイムやツールのガイドに進んでください。