人間の介入(HITL)
このガイドでは、SDK の承認ベースの人間の介入(HITL)フローについて説明します。ツール呼び出しに承認が必要な場合、SDK は実行を一時停止して interruptions を返し、後で同じ RunState から再開できるようにします。
この承認の仕組みは、現在のトップレベルのエージェントに限らず、実行全体が対象です。ツールが現在のエージェントに属する場合も、ハンドオフ先のエージェントに属する場合も、ネストされた agent.asTool() の実行に属する場合も、同じパターンが適用されます。ネストされた agent.asTool() の場合でも、中断は外側の実行に通知されるため、外側の result.state で承認または拒否し、元のルートの実行を再開します。
agent.asTool() では、承認は 2 つの異なる層で発生する可能性があります。エージェントツール自体が asTool({ needsApproval }) によって承認を要求する場合と、ネストされた実行の開始後に、そのエージェント内のツールが独自に承認を要求する場合です。どちらも、外側の実行における同じ中断フローで処理されます。
このページでは、interruptions による手動の承認フローを中心に説明します。アプリケーションがコードで判断できる場合、一部のツールタイプではプログラムによる承認コールバックもサポートされているため、一時停止せずに実行を続行できます。agent.asTool() 自体の設定については、ツールを参照してください。このページでは、その実行階層内のいずれかのツールが承認を必要とした後の動作を説明します。
computerTool() では、onSafetyCheck を使用して、Responses API が返す安全性チェックを受け入れるか拒否します。このコールバックは、id と code がどちらも空でない値を持つ保留中のチェックがあるコンピュータ呼び出しでのみ実行され、このページで説明する一時停止と再開による承認フローは使用しません。詳細とコード例については、コンピュータの安全性チェックを参照してください。
needsApproval オプションを true または真偽値を返す非同期関数に設定することで、承認を必要とするツールを定義できます。
import { tool } from '@openai/agents';import z from 'zod';
const sensitiveTool = tool({ name: 'cancelOrder', description: 'Cancel order', parameters: z.object({ orderId: z.number(), }), // always requires approval needsApproval: true, execute: async ({ orderId }, args) => { // prepare order return },});
const sendEmail = tool({ name: 'sendEmail', description: 'Send an email', parameters: z.object({ to: z.string(), subject: z.string(), body: z.string(), }), needsApproval: async (_context, { subject }) => { // check if the email is spam return subject.includes('spam'); }, execute: async ({ to, subject, body }, args) => { // send email },});- ツール呼び出しが実行される直前に、SDK はその承認ルール(
needsApprovalまたはリモート MCP の同等のルール)を評価します。 - 承認が必要で、まだ判断が保存されていない場合、そのツール呼び出しは実行されません。代わりに、実行に
RunToolApprovalItemが記録されます。 - そのターンの終了時に実行が一時停止し、保留中のすべての承認がエージェントの実行結果の
interruptions配列に返されます。これには、ネストされたagent.asTool()の実行内で要求された承認も含まれます。 - 保留中の各アイテムを
result.state.approve(interruption)またはresult.state.reject(interruption)で解決します。同じツールをその実行の残りの期間中ずっと承認済みまたは拒否済みにする場合は、{ alwaysApprove: true }または{ alwaysReject: true }を渡します。拒否する場合は、{ message: '...' }を渡して、その特定のツール呼び出しについてモデルに返す拒否メッセージを指定することもできます。 - 更新された
result.stateをrunner.run(agent, state)に渡して再開します。ここでagentは、その実行を開始した元のトップレベルのエージェントです。SDK は、ネストされたエージェントツールの実行も含めて、中断した時点から続行します。
デフォルトでは、関数ツールの入力ガードレールは承認後、ツールが実行される直前にのみ実行されます。承認待ちの要求が表示される前に、同じ入力ガードレールでローカル関数ツールの呼び出しを検証したい場合は、run() または Runner に toolExecution: { preApprovalInputGuardrails: true } を渡してください。承認前のガードレールが呼び出しを拒否した場合、SDK は承認のための中断を作成せず、ガードレールのメッセージをツール出力としてモデルに返します。呼び出しが許可された場合でも、実行は承認のために一時停止します。また、待機中にツール呼び出しが安全でなくなった可能性を考慮して、承認後に入力ガードレールが再度実行されます。
needsApproval が関数の場合、SDK はツールの引数が検査可能なオブジェクトにパースされた後にのみ、その関数を呼び出します。不正な JSON やオブジェクト以外の値に対しては安全側に倒し、SDK はコールバックの呼び出しやツールの実行をせずに承認を要求します。その呼び出しを承認してもツールは実行されず、通常の引数のパースエラー処理に進みます。Realtime 関数ツールも同じルールに従い、不正な呼び出しに対して tool_approval_requested を発行します。
{ alwaysApprove: true } または { alwaysReject: true } で作成された、継続して適用される判断は実行状態に保存されるため、後で同じ一時停止中の実行を再開する際も、toString() / fromString() を通じて保持されます。
GA モデルでは、コンピュータツールの中断は、1 つの computer_call に含まれるアクションのバッチを表す場合があります。SDK は実行前にアクションごとに needsApproval を評価するため、1 つの保留中の承認が、移動 + クリックのような一連の操作を対象にすることがあります。UI の表示に interruption.rawItem を使用する場合は、GA の actions 配列と従来の単一の action フィールドの両方に対応してください。
シリアライズされた RunState は、現在の computer というツール名と従来の computer_use_preview という名前の両方にわたってコンピュータの承認も保持するため、プレビュー版から GA への移行中でも、一時停止中の実行を問題なく再開できます。
message を指定しない場合、SDK は設定された toolErrorFormatter(存在する場合)にフォールバックし、次にデフォルトの拒否メッセージにフォールバックします。
保留中のすべての承認を一度に解決する必要はありません。一部のアイテムだけを承認または拒否して再実行した場合、解決済みの呼び出しは続行できますが、未解決のものは interruptions に残り、実行が再び一時停止します。
alwaysApprove: true または alwaysReject: true で作成された、継続して適用される判断は、その後の同じツールの呼び出しに対するデフォルトになります。特定の呼び出し ID に対する個別の判断は、この継続適用のデフォルトよりも優先されます。ほかの呼び出しのデフォルトを変更せずに、継続的に承認されているツールの 1 つの呼び出しを拒否したり、継続的に拒否されているツールの 1 つの呼び出しを承認したりできます。後でその個別の判断を置き換えた場合、その呼び出しには新しい個別の判断が適用され、残りの呼び出しには引き続き継続適用のデフォルトが使用されます。
再開前の入力の追加
Section titled “再開前の入力の追加”実行の一時停止中に新しいユーザー入力が届き、再開後の次のモデル呼び出しの前に取り込む必要がある場合は、RunState.addInput() を使用します。承認を解決し、同じ状態を Runner.run() に渡す前に入力を追加してください。取り込み待ちの入力はシリアライズされた状態の一部になるため、未解決の承認やローカルのツール処理によってモデル呼び出しが遅れる場合でも、toString() / fromString() を通じて保持されます。
state.pendingInput を読み取ると、取り込み待ちのアイテムの複製されたスナップショットを確認できます。また、再開前に state.clearPendingInput() を呼び出すと、それらをすべて削除できます。addInput() は文字列または入力アイテムの配列を受け取ります。終了状態、残りのターンがない状態、ツールの実行結果によって実行が終了する可能性がある中断など、状態が次のモデル呼び出しに安全に到達できない場合は、UserError を発生させます。
取り込まれると、取り込み待ちだった各入力エントリーは実行の newItems 内の RunInputItem になり、その元の入力アイテムは history に含まれます。ローカルの session を使用している場合、SDK はモデルへのリクエストを開始する前に、取り込まれた入力を一度だけ永続化します。conversationId または previousResponseId を使用している場合、入力はサーバーがレスポンスを受け付けるまで保留状態に残るため、受け付け前に発生したことが判明している失敗であれば、入力を失わずに再開できます。プロバイダーが、リクエストはすでに受け付けられた可能性があると報告した場合、SDK はその入力エントリーをチェックポイントに記録し、黙って再送するのではなく、安全側に倒して処理を停止します。安全でない再送を明示的に許可する別途の設定については、モデルのリトライを参照してください。
自動承認判断
Section titled “自動承認判断”手動の interruptions は最も汎用的なパターンですが、唯一の方法ではありません。
- ローカルの
shellTool()とapplyPatchTool()は、onApprovalを使用してコード内で即座に承認または拒否できます。 - リモート MCP ツールは、
requireApprovalとonApprovalを組み合わせて、同様にプログラムで判断できます。 - 通常の関数ツールは、このページの手動の中断フローを使用します。
これらのコールバックが判断を返すと、人間の応答を待つために一時停止することなく、実行が続行されます。Realtime セッション API については、音声エージェントの構築の承認フローを参照してください。
ストリーミングとセッション
Section titled “ストリーミングとセッション”同じ中断フローは、ストリーミングによる実行でも機能します。ストリーミングによる実行が一時停止したら、stream.completed を待ち、stream.interruptions を読み取って解決してください。再開後の出力も引き続きストリーミングする場合は、{ stream: true } を指定して run() を再度呼び出します。このパターンのストリーミング版については、ストリーミング中の人間の介入(HITL)を参照してください。
session も使用している場合は、RunState から再開する際も同じ session を渡し続けてください。そうすると、入力を再準備することなく、再開されたターンがセッションメモリに追加されます。セッションのライフサイクルの詳細については、セッションを参照してください。
以下は、ターミナルで承認を求め、状態を一時的にファイルに保存する、人間の介入(HITL)フローのより完全なコード例です。
// This local CLI trusts its saved state. Browser/mobile approval UIs should keep// snapshots on the server; see human-in-the-loop-server.ts in agent-patterns.import { z } from 'zod';import readline from 'node:readline/promises';import fs from 'node:fs/promises';import { Agent, run, tool, RunState, RunResult } from '@openai/agents';
const getWeatherTool = tool({ name: 'get_weather', description: 'Get the weather for a given city', parameters: z.object({ location: z.string(), }), needsApproval: async (_context, { location }) => { // forces approval to look up the weather in San Francisco return location === 'San Francisco'; }, execute: async ({ location }) => { return `The weather in ${location} is sunny`; },});
const dataAgentTwo = new Agent({ name: 'Data agent', instructions: 'You are a data agent', handoffDescription: 'You know everything about the weather', tools: [getWeatherTool],});
const agent = new Agent({ name: 'Basic test agent', instructions: 'You are a basic agent', handoffs: [dataAgentTwo],});
async function confirm(question: string) { const rl = readline.createInterface({ input: process.stdin, output: process.stdout, });
const answer = await rl.question(`${question} (y/n): `); const normalizedAnswer = answer.toLowerCase(); rl.close(); return normalizedAnswer === 'y' || normalizedAnswer === 'yes';}
async function main() { let result: RunResult<unknown, Agent<unknown, any>> = await run( agent, 'What is the weather in Oakland and San Francisco?', ); let hasInterruptions = result.interruptions?.length > 0; while (hasInterruptions) { // Store the current run state await fs.writeFile( 'result.json', JSON.stringify(result.state, null, 2), 'utf-8', );
// At this point, another process could review the saved state
// Read the saved state later const storedState = await fs.readFile('result.json', 'utf-8'); const state = await RunState.fromString(agent, storedState);
for (const interruption of result.interruptions) { const confirmed = await confirm( `Agent ${interruption.agent.name} would like to use the tool ${interruption.name} with "${interruption.arguments}". Do you approve?`, );
if (confirmed) { state.approve(interruption); } else { state.reject(interruption); } }
// Resume execution from the restored state result = await run(agent, state); hasInterruptions = result.interruptions?.length > 0; }
console.log(result.finalOutput);}
main().catch((error) => { console.dir(error, { depth: null });});エンドツーエンドで動作する版については、コード例の完全なスクリプトを参照してください。
承認に時間がかかる場合の対応
Section titled “承認に時間がかかる場合の対応”人間の介入(HITL)フローは、サーバーを稼働させ続けなくても長期間中断できるように設計されています。リクエストの処理を終了して後で続行する必要がある場合は、状態をシリアライズして後で再開できます。
result.state.toString()(または JSON.stringify(result.state))を使用して状態をシリアライズし、後でそのシリアライズされた状態を RunState.fromString(agent, serializedState) に渡すことで再開できます。ここで agent は、実行全体を開始したエージェントのインスタンスです。
承認された関数ツールの実行結果が実行の最終出力になり得る場合、出力ガードレールによって再開の条件がより厳しくなります。現在の RunState スキーマは、SDK が証明できる場合に、現在のレスポンスで生成されたアイテムの正確な所有関係を記録します。そのため、出力を含むサポート対象の部分承認チェックポイントは、シリアライズされた状態を介して保存・復元できます。SDK は、モデル、ツール、セッションで追加の副作用が発生する前に、その所有関係を検証します。古いスナップショットや、所有関係が欠落している、不正である、または曖昧なチェックポイントでは、引き続き安全側に倒し、UserError で処理を停止します。この場合は、安全な入力から新しい実行を開始してください。同じエージェントグラフを再構築し、元の toolUseBehavior を維持してください。元のアイテムを再実行して所有関係のエラーを回避しないでください。
RunState がシリアライズされると、SDK はハンドオフと Agent.asTool() のグラフに対して、安定したエージェント識別情報を記録します。これにより、実行を再開するプロセスが同じエージェントグラフを再構築する限り、異なるエージェントが同じ name を共有していても、一時停止中の実行を再開できます。
RunState.fromString(agent, serializedState) に渡す agent は、その再構築されたグラフのルートです。デシリアライズ中、SDK はそのエージェントのハンドオフと Agent.asTool() の参照をたどり、状態内のシリアライズされたすべてのエージェント参照を、再構築されたグラフに照らして解決します。これには、現在のエージェントと、生成されたアイテム、処理済みのモデルレスポンス、キューに入っている次のステップが保持するネストされた参照が含まれます。
モデルやツールが別のランタイムでラップされたエージェントなど、置き換えたグラフで再開する必要がある場合は、元のグラフで状態をデシリアライズし、再度シリアライズしてから、その文字列を置き換え後のルートエージェントでデシリアライズしてください。state.setCurrentAgent(agent) を呼び出しても、アクティブなエージェントが変わるだけで、デシリアライズ時にすでに解決されたネストされた参照は書き換えられません。
再開するプロセスで新しいコンテキストオブジェクトを注入する必要がある場合は、代わりに RunState.fromStringWithContext(agent, serializedState, context, { contextStrategy }) を使用してください。
contextStrategy: 'merge'(デフォルト)は、指定されたRunContextを保持し、シリアライズされた承認状態をマージします。また、新しいコンテキストでtoolInputがまだ定義されていない場合は、シリアライズされたtoolInputを復元します。contextStrategy: 'replace'は、指定されたRunContextをそのまま使用して実行を再構築します。
シリアライズされた実行状態には、アプリケーションのコンテキストに加えて、承認、使用量、ネストされた toolInput、ネストされたエージェントツールの保留中の再開処理など、SDK が管理するランタイムメタデータが含まれます。シリアライズされた状態を保存または送信する予定がある場合は、runContext.context を永続化されるデータとして扱い、機密情報を状態と一緒に移動させる意図がある場合を除き、そこに格納しないでください。
デフォルトでは、誤って機密情報を永続化しないように、トレーシング用の API キーはシリアライズされた状態から除外されます。トレーシングの認証情報を状態と一緒に移動させる必要があることを意図している場合にのみ、result.state.toString({ includeTracingApiKey: true }) を渡してください。
シリアライズされた状態は、サーバー側のデータベースなど、アプリケーションが管理するストレージに保存してください。
承認状態のサーバーでの保持
Section titled “承認状態のサーバーでの保持”シリアライズされた RunState には、承認判断、保留中のツール呼び出し、ツールの引数、アプリケーションのコンテキストなどの実行状態が含まれます。RunState.fromString() はその状態を復元しますが、このメソッドはスナップショットの真正性の検証も、送信者の本人確認も行いません。信頼できるストレージにあるスナップショット、またはアプリケーションでスナップショット全体の完全性、所有権、リプレイ対策を検証済みのものだけをデシリアライズしてください。スキーマ検証やツール呼び出しのフィンガープリントは、スナップショットの真正性を保証しません。エージェントや生成アイテムの所有関係についての SDK 内の参照情報も、アプリケーションユーザーの認可にはなりません。
ブラウザーやモバイルの承認インターフェースでは、完全なスナップショットを、アプリケーションが管理するサーバー側のストレージに保持してください。レビュー担当者には、閲覧が認可された表示用の詳細情報と、保留中の判断に対応する不透明な識別子だけを送信してください。実行 ID や判断 ID は、認可の証明にはなりません。ツール名と引数は、信頼できない表示コンテンツとして扱ってください。機密性の高い値を除外し、HTML として表示する際にはコンテンツをエスケープしてください。完全な実行結果とエラーはサーバーに保持し、アプリケーションが選択した出力だけをクライアントに返してください。
判断が届いたら、サーバーは次の処理を行う必要があります。
- アプリケーションのセッションまたは認証ミドルウェアを使って、レビュー担当者を認証します。認証済みのユーザー識別情報を承認リクエストの本文から取得してはいけません。
- 保存された実行と、選択された保留中の呼び出しに対して、レビュー担当者を認可します。
- 判断の識別子と真偽値の判断を、サーバーに保存された保留中のリクエストに照らして検証します。置き換え用のツール呼び出し、引数、承認レコード、シリアライズされた状態をクライアントから受け入れないでください。
- デシリアライズと実行の再開の前に、所有権の確認と保留中のリクエストの消費をアトミックに行います。同時送信や再送信によって、同じスナップショットが二度再開されてはいけません。共有ストレージでは、トランザクションまたは同等のアトミックな条件付き状態遷移を使用してください。
- サーバーが保持するスナップショットを読み込み、
state.getInterruptions()で保留中のアイテムを取得し、実行を再開する前に、それらのアイテムに対してのみstate.approve()またはstate.reject()を適用します。
次のコード例では、バッチ内の保留中の呼び出しすべてに対して、それぞれ 1 つの判断を要求します。これはアプリケーションのポリシーです。SDK は、前述のとおり部分的な承認もサポートしています。このストアの利用範囲は、1 つのプロセス内の 1 つのイベントループに限られます。所有者の確認、検証、消費の間に await は入りません。デシリアライズや実行が失敗した場合、または実行がキャンセルされた場合も、リクエストは消費済みのままです。消費処理は、このスナップショットの再送信を防ぎますが、ツールの副作用が厳密に 1 回だけ発生することを保証するものではありません。復旧や別の実行を開始する前に、完了済み、または成否が不明なツールの副作用を照合して整合性を確保してください。
import { randomUUID } from 'node:crypto';import { Agent, Runner, RunState, type RunResult } from '@openai/agents';import { z } from 'zod';
export type PendingApproval = { kind: 'approval'; requestId: string; prompts: { decisionId: string; toolName: string; arguments: string }[];};
type StoredRun = { ownerId: string; snapshot: string; decisionIds: string[];};
// Simulation only: one event loop in one process. Production storage needs an// atomic owner-checked consume operation and bounded retention. Consumption is// permanent even after failure/cancellation; reconcile side effects before retry.export class ApprovalServer { #agent: Agent; #runner = new Runner({ tracingDisabled: true }); #pending = new Map<string, StoredRun>();
constructor(agent: Agent) { this.#agent = agent; }
// An HTTP adapter must obtain this identity from trusted authentication // middleware and apply request/CSRF protections. Never read it from the body. async start(authenticatedUserId: string, message: string) { const result = await this.#runner.run(this.#agent, message); return this.#save(authenticatedUserId, result); }
#save<TContext, TAgent extends Agent<any, any>>( ownerId: string, result: RunResult<TContext, TAgent>, ) { const interruptions = result.state.getInterruptions(); if (interruptions.length === 0) { // RunResult stays on the server; the app selects what the client may see. return { kind: 'completed' as const, output: result.finalOutput }; } const requestId = randomUUID(); const decisionIds = interruptions.map(() => randomUUID()); this.#pending.set(requestId, { ownerId, snapshot: result.state.toString(), decisionIds, }); const response: PendingApproval = { kind: 'approval', requestId, // Detached display values only. Filter arguments for the reviewer's access // policy; this demo uses synthetic weather data. Escape HTML in a web UI. prompts: interruptions.map((item, index) => ({ decisionId: decisionIds[index], toolName: item.name ?? 'unknown_tool', arguments: item.arguments ?? '', })), }; return response; }
async decide( authenticatedUserId: string, requestId: string, decisions: unknown, signal?: AbortSignal, ) { const stored = this.#pending.get(requestId); if (!stored || stored.ownerId !== authenticatedUserId) { throw new Error('Approval request is unavailable.'); } // Validate JSON request data, not client-supplied calls, state, or identity. const parsed = z.record(z.string(), z.boolean()).safeParse(decisions); if ( !parsed.success || Object.keys(parsed.data).length !== stored.decisionIds.length || !stored.decisionIds.every((id) => Object.prototype.hasOwnProperty.call(parsed.data, id), ) ) { throw new Error( 'Provide one boolean decision for every pending tool call.', ); } // No await between the owner check and consume. The parsed decisions are a // detached copy, so client mutation while deserialization awaits has no effect. this.#pending.delete(requestId); const state = await RunState.fromString(this.#agent, stored.snapshot); const interruptions = state.getInterruptions(); for (const [index, interruption] of interruptions.entries()) { if (parsed.data[stored.decisionIds[index]]) { state.approve(interruption); } else { state.reject(interruption); } } const result = await this.#runner.run(this.#agent, state, { signal }); return this.#save(authenticatedUserId, result); }}完全なコード例については、CLI クライアント/サーバーのシミュレーションを参照してください。これは、そのままデプロイできる HTTP サービスではありません。本番アプリケーションでは、信頼できる認証、表示する詳細情報と選択された呼び出しに対する認可、該当する場合のリクエスト保護と CSRF 対策、ストレージでのデータ保持の上限、共有ストレージでのアトミックな消費処理、復旧ポリシーを用意する必要があります。この CLI は合成されたツールデータを使用し、トレーシングを無効にしています。実際のアプリケーションのスナップショットや診断情報には、機密データが含まれる可能性があります。
contextStrategy: 'replace' を指定して RunState.fromStringWithContext() を使用しても、シリアライズされた承認レコードだけを削除しても、信頼できないスナップショットが安全になるわけではありません。ほかのフィールドが引き続き実行を制御します。クライアントがスナップショット全体を転送する場合は、デシリアライズの前に、スナップショット全体の完全性を検証し、認可されたユーザーおよび実行に紐付け、リプレイを防止してください。完全性の検証は、スナップショットを暗号化したり、その内容をクライアントから隠したりするものではありません。
保留中のタスクのバージョン管理
Section titled “保留中のタスクのバージョン管理”承認リクエストに時間がかかり、エージェントの定義を適切にバージョン管理するか、Agents SDK のバージョンを上げる予定がある場合は、現時点では、パッケージエイリアスを使って Agents SDK の 2 つのバージョンを並行してインストールし、独自の分岐ロジックを実装することをお勧めします。
具体的には、独自のコードにバージョン番号を付け、シリアライズされた状態と一緒に保存して、デシリアライズ時に正しいバージョンのコードを使用するように振り分けます。