人間の介入(HITL)
このガイドでは、SDK に組み込まれた Human in the loop (人間の介入) サポートを使って、人による介入に基づきエージェントの実行を一時停止・再開する方法を説明します。
現在の主なユースケースは、機密性の高いツール実行に対する承認を求めることです。
承認リクエスト
Section titled “承認リクエスト”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 },});
- エージェントがツール(複数の可能性あり)を呼び出すと判断した場合、
needsApproval
を評価してそのツールに承認が必要か確認します - 承認が必要な場合、エージェントはすでに承認または却下されているかを確認します
- 承認または却下が行われていない場合、ツール呼び出しを実行できない旨の固定メッセージがエージェントに返されます
- 承認 / 却下が未処理である場合、ツール承認リクエストが発火します
- エージェントはすべてのツール承認リクエストを収集し、実行を中断します
- 中断がある場合、実行結果 には保留中のステップを表す
interruptions
配列が含まれます。ツール呼び出しに確認が必要な場合、type: "tool_approval_item"
のToolApprovalItem
が現れます - ツール呼び出しを承認または却下するには、
result.state.approve(interruption)
またはresult.state.reject(interruption)
を呼び出します - すべての中断を処理した後、
result.state
をrunner.run(agent, state)
に渡して実行を再開できます。ここでagent
は全体の実行を開始した元のエージェントです - フローは手順 1 から再開されます
以下は、ターミナルで承認を促し、状態を一時的にファイルへ保存する 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.rawItem.name} with "${interruption.rawItem.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 });});
動作するエンドツーエンド版は the full example script を参照してください。
より長い承認待ち時間への対応
Section titled “より長い承認待ち時間への対応”Human in the loop (人間の介入) フローは、サーバーを稼働し続けることなく長時間中断可能なように設計されています。リクエストをいったん終了して後から再開したい場合は、状態をシリアライズして後で再開できます。
JSON.stringify(result.state)
を使って状態をシリアライズし、後でシリアライズ済み状態を RunState.fromString(agent, serializedState)
に渡すことで再開できます。ここで agent
は全体の実行を開始したエージェントのインスタンスです。
この方法により、シリアライズした状態をデータベースやリクエストと一緒に保存できます。
保留タスクのバージョン管理
Section titled “保留タスクのバージョン管理”承認リクエストに時間がかかり、エージェント定義を意味のある形でバージョン管理したい、または Agents SDK のバージョンを上げたい場合は、パッケージのエイリアスを使用して 2 つの Agents SDK バージョンを並行インストールし、独自の分岐ロジックを実装することを現時点では推奨します。
実務的には、自身のコードにバージョン番号を割り当て、それをシリアライズした状態とともに保存し、デシリアライズ時に適切なコードのバージョンへ誘導することを意味します。