コンテンツにスキップ

人間の介入（HITL）

このガイドでは、 SDK の承認ベースの Human in the loop (人間の介入) フローを扱います。ツール呼び出しに承認が必要な場合、 SDK は実行を一時停止し、 interruptions を返し、同じ RunState から後で再開できるようにします。

この承認の対象範囲は実行全体であり、現在のトップレベルエージェントに限定されません。同じパターンは、ツールが現在のエージェントに属する場合、ハンドオフ経由で到達したエージェントに属する場合、またはネストされた agent.asTool() 実行に属する場合にも適用されます。ネストされた agent.asTool() の場合でも、中断は外側の実行に現れるため、外側の result.state で承認または拒否し、元のルート実行を再開します。

agent.asTool() では、承認は 2 つの異なるレイヤーで発生することがあります。エージェントツール自体が asTool({ needsApproval }) によって承認を必要とする場合と、ネストされたエージェント内のツールがネストされた実行開始後に独自の承認を要求する場合です。どちらも同じ外側の実行の中断フローで処理されます。

このページでは、 interruptions を介した手動承認フローに焦点を当てます。アプリがコードで判断できる場合、一部のツールタイプはプログラムによる承認コールバックもサポートしており、実行を一時停止せずに継続できます。 agent.asTool() 自体を設定している場合は、ツールガイド を参照してください。このページでは、その実行階層内のいずれかのツールが承認を必要とした後に何が起こるかを扱います。

承認フロー

Section titled “承認フロー”

needsApproval オプションを true に設定するか、 boolean を返す非同期関数に設定することで、承認を必要とするツールを定義できます。

ツール承認の定義
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
  },
});

フロー

Section titled “フロー”
  1. ツール呼び出しが実行される直前に、 SDK はその承認ルール（ needsApproval または Hosted MCP に相当するもの）を評価します
  2. 承認が必要で、まだ決定が保存されていない場合、ツール呼び出しは実行されません。代わりに、実行は RunToolApprovalItem を記録します
  3. そのターンの終わりに、実行は一時停止し、保留中のすべての承認を エージェントの実行結果 の interruptions 配列で返します。これには、ネストされた agent.asTool() 実行内で発生した承認も含まれます
  4. result.state.approve(interruption) または result.state.reject(interruption) で各保留項目を解決します。同じツールをその実行の残りでも承認または拒否状態のままにしたい場合は、 { alwaysApprove: true } または { alwaysReject: true } を渡します。拒否時には、 { message: '...' } を渡して、その特定のツール呼び出しについてモデルに返される拒否メッセージを制御することもできます
  5. 更新した result.state を runner.run(agent, state) に戻して渡して再開します。ここで agent は、その実行の元のトップレベルエージェントです。 SDK は、中断された地点から、ネストされたエージェントツール実行も含めて継続します

{ alwaysApprove: true } または { alwaysReject: true } で作成された固定的な決定は実行状態に保存されるため、後で同じ一時停止中の実行を再開する際にも toString() / fromString() をまたいで維持されます。

コンピュータツールの中断は、 GA モデルでは 1 つの computer_call に含まれる複数アクションを表すことがあります。 SDK は実行前にアクションごとに needsApproval を評価するため、 1 つの保留中の承認で、移動 + クリックのような一連の操作を対象にできる場合があります。 UI を描画するために interruption.rawItem を確認する場合は、 GA の actions 配列と、従来の単一 action フィールドの両方に対応してください。

シリアライズされた RunState は、現在の computer ツール名と従来の computer_use_preview 名の両方にまたがってコンピュータ承認も保持するため、 preview から GA への移行中でも一時停止した実行を問題なく再開できます。

message を指定しない場合、 SDK は設定済みの toolErrorFormatter （存在する場合）にフォールバックし、その後デフォルトの拒否テキストにフォールバックします。

同じパスですべての保留中の承認を解決する必要はありません。一部の項目だけを承認または拒否した状態で再実行した場合、解決済みの呼び出しは継続でき、未解決のものは interruptions に残って再び実行を一時停止させます。

自動承認の決定

Section titled “自動承認の決定”

手動の interruptions はもっとも一般的なパターンですが、それだけではありません。

  • ローカルの shellTool() と applyPatchTool() は、 onApproval を使ってコード内ですぐに承認または拒否できます
  • Hosted MCP ツールは、同種のプログラムによる決定のために requireApproval と onApproval を組み合わせて使えます
  • 通常の関数ツールは、このページの手動中断フローを使います

これらのコールバックが決定を返すと、人間の応答のために一時停止することなく実行が継続されます。 Realtime / 音声セッション API については、音声エージェントの構築 の承認フローを参照してください。

ストリーミングとセッション

Section titled “ストリーミングとセッション”

同じ中断フローはストリーミング実行でも機能します。ストリーミング実行が一時停止したら、 stream.completed を待ち、 stream.interruptions を読み取り、それらを解決し、再開後の出力もストリーミングを継続したい場合は { stream: true } を指定して再度 run() を呼び出します。このパターンのストリーミング版については、ストリーミング中の Human in the loop (人間の介入) を参照してください。

session も使用している場合は、 RunState から再開する際に同じ session を引き続き渡してください。すると再開されたターンは、入力を再準備することなくセッションメモリに追加されます。セッションのライフサイクルの詳細は、セッションガイド を参照してください。

例

Section titled “例”

以下は、ターミナルで承認を求め、一時的に状態をファイルに保存する、より完全な Human in the loop (人間の介入) フローの例です。

Human in the loop
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) {
    // storing
    await fs.writeFile(
      'result.json',
      JSON.stringify(result.state, null, 2),
      'utf-8',
    );


    // from here on you could run things on a different thread/process


    // reading later on
    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 of the current 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 “長い承認待ち時間への対応”

Human in the loop (人間の介入) フローは、サーバーを動かし続けることなく、長時間にわたって中断可能であるように設計されています。リクエストを終了して後で再開する必要がある場合は、状態をシリアライズして後で再開できます。

状態は result.state.toString() （または JSON.stringify(result.state) ）を使ってシリアライズでき、後で agent を全体の実行を開始したエージェントのインスタンスとして RunState.fromString(agent, serializedState) にシリアライズ済み状態を渡すことで再開できます。

RunState をシリアライズする場合は、ハンドオフおよび Agent.asTool() グラフ内のすべてのエージェントに一意な name 値を使用してください。エージェント名は再開時にシリアライズ済みエージェントを解決するために使われ、重複した名前があると状態のシリアライズ時またはデシリアライズ時にエラーになります。

再開されたプロセスで新しいコンテキストオブジェクトを注入する必要がある場合は、代わりに RunState.fromStringWithContext(agent, serializedState, context, { contextStrategy }) を使ってください。

  • contextStrategy: 'merge' （デフォルト）は、提供された RunContext を保持し、シリアライズされた承認状態をマージし、新しいコンテキストでまだ定義されていない場合はシリアライズされた toolInput を復元します
  • contextStrategy: 'replace' は、提供された RunContext をそのまま使って実行を再構築します

シリアライズされた実行状態には、アプリのコンテキストに加えて、承認、使用量、ネストされた toolInput、保留中のネストされたエージェントツール再開などの SDK 管理ランタイムメタデータも含まれます。シリアライズ済み状態を保存または転送する予定がある場合は、 runContext.context を永続化されるデータとして扱い、意図的に状態と一緒に移動させたい場合を除いて、そこに秘密情報を置かないようにしてください。

デフォルトでは、誤って秘密情報を永続化しないよう、トレーシング API キーはシリアライズ済み状態から除外されます。トレーシング資格情報を状態とともに移動する必要が意図的にある場合にのみ、 result.state.toString({ includeTracingApiKey: true }) を渡してください。

これにより、シリアライズ済み状態をデータベースに保存したり、リクエストと一緒に保存したりできます。

保留中タスクのバージョニング

Section titled “保留中タスクのバージョニング”

承認リクエストに長い時間がかかり、エージェント定義を意味のある形でバージョン管理したい場合や Agents SDK のバージョンを上げたい場合は、現時点では package alias を使って Agents SDK の 2 つのバージョンを並行してインストールし、独自の分岐ロジックを実装することを推奨します。

実際には、これは自分のコードに独自のバージョン番号を割り当て、それをシリアライズ済み状態とともに保存し、デシリアライズ時に正しいバージョンのコードへ誘導することを意味します。