エージェントの実行
エージェントは単独では何もしません。Runner クラスまたは run() ユーティリティを使って 実行 します。
ターンの実行、イベントのストリーミング、会話状態の管理を行う際は、エージェントの次にこのページをお読みください。エージェントをどのように定義するかをまだ検討している場合は、まずエージェントから始めてください。
import { Agent, run } from '@openai/agents';
const agent = new Agent({ name: 'Assistant', instructions: 'You are a helpful assistant',});
const result = await run( agent, 'Write a haiku about recursion in programming.',);console.log(result.finalOutput);
// Code within the code,// Functions calling themselves,// Infinite loop's dance.カスタムのランナーが必要ない場合は、シングルトンのデフォルト Runner インスタンスを実行する run() ユーティリティも使用できます。
または、独自のランナーインスタンスを作成できます。
import { Agent, Runner } from '@openai/agents';
const agent = new Agent({ name: 'Assistant', instructions: 'You are a helpful assistant',});
// You can pass custom configuration to the runnerconst runner = new Runner();
const result = await runner.run( agent, 'Write a haiku about recursion in programming.',);console.log(result.finalOutput);
// Code within the code,// Functions calling themselves,// Infinite loop's dance.エージェントを実行すると、最終出力と実行の全履歴を含むエージェントの実行結果オブジェクトが返されます。
Runner のライフサイクルと設定
Section titled “Runner のライフサイクルと設定”エージェントループ
Section titled “エージェントループ”Runner の run メソッドを使用する際は、開始エージェントと入力を渡します。入力には、文字列(ユーザーメッセージとして扱われます)、または OpenAI Responses API の項目である入力項目のリストを指定できます。
その後、ランナーは次のループを実行します。
- 現在の入力を使って、現在のエージェントのモデルを呼び出します。
- LLM のレスポンスを確認します。
- 最終出力 → 結果を返します。
- ハンドオフ → 新しいエージェントに切り替え、蓄積された会話履歴を保持して、1 に戻ります。
- ツール呼び出し → ツールを実行し、その結果を会話に追加して、1 に戻ります。
maxTurnsがnullでない限り、maxTurnsに達するとMaxTurnsExceededErrorをスローします。
Runner のライフサイクル
Section titled “Runner のライフサイクル”アプリの起動時に Runner を作成し、リクエスト間で再利用します。このインスタンスには、モデルプロバイダーやトレーシングオプションなどのグローバル設定が保存されます。別の Runner を作成するのは、まったく異なる設定が必要な場合だけにしてください。シンプルなスクリプトでは、内部でデフォルトのランナーを使用する run() を呼び出すこともできます。
実行時の引数
Section titled “実行時の引数”run() メソッドには、実行を開始する初期エージェント、実行への入力、および一連のオプションを渡します。
入力には、文字列(ユーザーメッセージとして扱われます)、入力項目のリスト、または人間の介入(HITL)を伴うエージェントを構築する場合は RunState オブジェクトを指定できます。
追加のオプションは次のとおりです。
| オプション | デフォルト | 説明 |
|---|---|---|
stream | false | true の場合、呼び出しは StreamedRunResult を返し、モデルからイベントが届くたびに発行します。 |
context | – | すべてのツール / ガードレール / ハンドオフに渡されるコンテキストオブジェクトです。詳しくはコンテキスト管理をご覧ください。 |
maxTurns | 10 | 安全のための上限です。到達すると MaxTurnsExceededError をスローします。上限を無効にするには null を渡します。 |
signal | – | キャンセル用の AbortSignal です。 |
session | – | セッションの永続化の実装です。セッションをご覧ください。 |
sessionInputCallback | – | セッション履歴と新しい入力をマージするカスタムロジックです。モデル呼び出しの前に実行されます。セッションをご覧ください。 |
callModelInputFilter | – | モデルを呼び出す直前にモデル入力(項目と任意の instructions)を編集するフックです。モデル呼び出し入力フィルターをご覧ください。 |
toolErrorFormatter | – | モデルに返すツールエラーメッセージをカスタマイズするフックです。ツールエラーフォーマッターをご覧ください。 |
reasoningItemIdPolicy | – | 以前の実行項目をモデル入力に戻す際に、推論項目の id を保持するか省略するかを制御します。推論項目の ID ポリシーをご覧ください。 |
tracing | – | 実行ごとのトレーシング設定のオーバーライドです。デフォルトのタスク / ターンのスパン階層を省略するには、includeTaskAndTurnSpans: false を設定します。 |
sandbox | – | SandboxAgent の実行用のサンドボックスクライアント、ライブセッション、セッション状態、スナップショット、マニフェストのオーバーライド、または同時実行数の制限です。コンセプトをご覧ください。 |
toolExecution | – | ローカルツール呼び出しに対する SDK 側の実行設定です。toolExecution.maxFunctionToolConcurrency を使って同時に実行する関数ツールの数を制限し、toolExecution.preApprovalInputGuardrails を使って承認待ちリクエストの前に関数ツールの入力ガードレールを実行します。 |
toolNotFoundBehavior | 'raise_error' | モデルが出力した、対応するツールが見つからない関数ツール呼び出しの扱いを制御します。モデルにツールエラーを返して実行を継続するには、'return_error_to_model' を使用します。 |
toolNameCollisionPolicy | 'warn' | 有効な関数ツール名とハンドオフ名の衝突を制御します。警告を出して現在のディスパッチで優先されるものだけを公開する代わりに、モデルへのリクエスト前にエラーにするには、'error' を使用します。 |
errorHandlers | – | サポートされているランタイムエラーのハンドラーです。エラーハンドラーをご覧ください。 |
conversationId | – | サーバー側の会話を再利用します(OpenAI Responses API + Conversations API のみ)。 |
previousResponseId | – | 会話を作成せずに、前回の Responses API 呼び出しから継続します(OpenAI Responses API のみ)。 |
ストリーミング
Section titled “ストリーミング”ストリーミングでは、LLM の実行中にもイベントが公開されます。StreamedRunResult は実行の進行に伴って情報を蓄積します。実行結果の completed Promise が解決されると、実行結果のサマリープロパティに、新たに生成されたすべての出力が含まれます。for await ループを使ってストリーミングイベントを反復処理できます。詳しくはストリーミングをご覧ください。
独自の Runner インスタンスを作成する場合は、RunConfig オブジェクトを渡してランナーを設定できます。
| フィールド | 型 | 用途 |
|---|---|---|
model | string | Model | 実行内の すべて のエージェントに特定のモデルを強制的に使用させます。 |
modelProvider | ModelProvider | モデル名を解決します。デフォルトは OpenAI プロバイダーです。 |
modelSettings | ModelSettings | エージェントごとの設定をオーバーライドするグローバルな調整パラメーターです。オプトインのリトライ設定などの詳細は、モデルをご覧ください。 |
handoffInputFilter | HandoffInputFilter | ハンドオフ時に入力項目を変更します(ハンドオフ自体にフィルターが定義されていない場合)。 |
inputGuardrails | InputGuardrail[] | 最初 のユーザー入力に適用されるガードレールです。 |
outputGuardrails | OutputGuardrail[] | 最終 出力に適用されるガードレールです。 |
tracingDisabled | boolean | OpenAI のトレーシングを完全に無効にします。 |
traceIncludeSensitiveData | boolean | スパンを引き続き発行しながら、LLM / ツールの入力と出力をトレースから除外します。 |
workflowName | string | Traces ダッシュボードに表示され、関連する実行をグループ化するのに役立ちます。 |
traceId / groupId | string | SDK に生成させる代わりに、トレース ID またはグループ ID を手動で指定します。 |
traceMetadata | Record<string, string> | すべてのスパンに付加する任意のメタデータです。 |
tracing | TracingConfig | エクスポート用の API キーや includeTaskAndTurnSpans など、ランナーレベルのトレーシングのデフォルト設定です。個々の実行オプションでこれらの値をオーバーライドできます。 |
sessionInputCallback | SessionInputCallback | このランナーで行うすべての実行の、デフォルトの履歴マージ戦略です。 |
callModelInputFilter | CallModelInputFilter | 各モデル呼び出しの前にモデル入力を編集するグローバルフックです。 |
toolErrorFormatter | ToolErrorFormatter | モデルに返すツールエラーメッセージをカスタマイズするグローバルフックです。 |
reasoningItemIdPolicy | ReasoningItemIdPolicy | 生成済みの項目を後続のモデル呼び出しで再び入力として使用する際に、推論項目の id を保持するか省略するかを決めるデフォルトのポリシーです。 |
sandbox | SandboxRunConfig | SandboxAgent の実行に使用する、デフォルトのサンドボックスランタイム設定です。 |
toolExecution | ToolExecutionConfig | ローカルツール呼び出しに対する SDK 側のデフォルトの実行設定です。maxFunctionToolConcurrency は、各ターンでのローカル関数ツールの同時実行数を制限します。未設定または null の場合、ターン内で出力されたすべての関数ツール呼び出しを開始します。preApprovalInputGuardrails は、承認待ちリクエストの前に関数ツールの入力ガードレールを実行する設定を有効にします。 |
toolNotFoundBehavior | ToolNotFoundBehavior | 対応するツールが見つからない関数ツール呼び出しに対するデフォルトの動作です。'raise_error' は ModelBehaviorError を発生させます。'return_error_to_model' はモデルにツールエラーを返し、実行を継続できるようにします。 |
toolNameCollisionPolicy | ToolNameCollisionPolicy | 有効な関数ツール名とハンドオフ名に対するデフォルトの衝突ポリシーです。'warn' はログを記録し、現在のディスパッチで優先されるものを公開します。'error' はモデルを呼び出す前に UserError を発生させます。 |
toolExecution.maxFunctionToolConcurrency は 1 以上の整数である必要があります。この設定は、SDK 側でのローカル関数ツールの実行のみを制限します。プロバイダー側の modelSettings.parallelToolCalls は変更しません。
toolExecution.preApprovalInputGuardrails はデフォルトで無効です。true に設定すると、承認を必要とするローカル関数ツールは、SDK が承認待ちの中断を記録する前に入力ガードレールを実行します。ガードレールが rejectContent を返した場合、SDK は承認を求める代わりに、その拒否メッセージをツール出力として返します。ガードレールが呼び出しを許可した場合は、引き続き承認リクエストが発生し、承認が解決された後、ツール実行の直前に同じ入力ガードレールが再度実行されます。
toolNameCollisionPolicy は、有効な関数ツールとハンドオフ間の衝突のみを制御します。名前空間付きツール、遅延ツール、重複するローカル MCP ツール名に対する既存の厳格な検証は変更されません。
状態と会話の管理
Section titled “状態と会話の管理”メモリ戦略の選択
Section titled “メモリ戦略の選択”次のターンに状態を引き継ぐ一般的な方法は 4 つあります。
| 戦略 | 状態の保存先 | 適した用途 | 次のターンで渡すもの |
|---|---|---|---|
result.history | アプリのメモリ | 小規模なチャットループ、完全な手動制御、任意のプロバイダー | result.history |
session | ストレージ + SDK | 永続的なチャット状態、再開可能な実行、カスタムストア | 同じ session インスタンス(またはストアを利用するインスタンス) |
conversationId | OpenAI Conversations API | ワーカー / サービス間で共有するサーバー側の状態 | 同じ conversationId と、新しいユーザーターンのみ |
previousResponseId | OpenAI Responses API のみ | 会話を作成せずに行う、最もシンプルなサーバー管理の継続 | result.lastResponseId と、新しいユーザーターンのみ |
result.history と session はクライアント側で管理されます。conversationId と previousResponseId は OpenAI 側で管理され、OpenAI Responses API を使用している場合にのみ適用されます。ほとんどのアプリケーションでは、会話ごとに 1 つの永続化戦略を選んでください。クライアント管理の履歴とサーバー管理の状態を混在させると、両方のレイヤーを意図的に整合させない限り、コンテキストが重複する可能性があります。
サンドボックスエージェントには、稼働中のサンドボックスワークスペースという別の状態レイヤーがあります。会話履歴には通常の SDK の session、conversationId、または previousResponseId を使い、サンドボックスのファイルシステムの状態には sandbox.session、sandbox.sessionState、RunState、またはスナップショットを使ってください。ワークスペースのライフサイクルについては、コンセプトをご覧ください。
会話 / チャットスレッド
Section titled “会話 / チャットスレッド”runner.run()(または run() ユーティリティ)の各呼び出しは、アプリケーションレベルの会話における 1 ターン を表します。RunResult のどこまでをエンドユーザーに表示するかは自由に選べます。finalOutput だけを表示する場合もあれば、生成されたすべての項目を表示する場合もあります。
import { Agent, run } from '@openai/agents';import type { AgentInputItem } from '@openai/agents';
let thread: AgentInputItem[] = [];
const agent = new Agent({ name: 'Assistant',});
async function userSays(text: string) { const result = await run( agent, thread.concat({ role: 'user', content: text }), );
thread = result.history; // Carry over history + newly generated items return result.finalOutput;}
await userSays('What city is the Golden Gate Bridge in?');// -> "San Francisco"
await userSays('What state is it in?');// -> "California"対話型のバージョンについては、チャットのコード例をご覧ください。
サーバー管理の会話
Section titled “サーバー管理の会話”ターンごとにローカルの会話履歴全体を送信する代わりに、OpenAI Responses API に会話履歴を永続化させることができます。これは、長い会話や複数のサービスを連携させる場合に便利です。以下のどちらのサーバー管理方式でも、各リクエストには新しいターンの入力のみを渡します。API が以前の状態を再利用します。詳しくは、会話状態ガイドをご覧ください。
OpenAI は、サーバー側の状態を再利用する 2 つの方法を提供しています。
1. 会話全体に対する conversationId
Section titled “1. 会話全体に対する conversationId”Conversations API を使って一度会話を作成し、その ID をすべてのターンで再利用できます。SDK は、新たに生成された項目のみを自動的に含めます。
import { Agent, run } from '@openai/agents';import { OpenAI } from 'openai';
const agent = new Agent({ name: 'Assistant', instructions: 'Reply very concisely.',});
async function main() { // Create a server-managed conversation: const client = new OpenAI(); const { id: conversationId } = await client.conversations.create({});
const first = await run(agent, 'What city is the Golden Gate Bridge in?', { conversationId, }); console.log(first.finalOutput); // -> "San Francisco"
const second = await run(agent, 'What state is it in?', { conversationId }); console.log(second.finalOutput); // -> "California"}
main().catch(console.error);2. 前のターンから継続するための previousResponseId
Section titled “2. 前のターンから継続するための previousResponseId”まずは Responses API だけで始めたい場合は、前のレスポンスから返された ID を使って各リクエストを連鎖させることができます。これにより、会話リソース全体を作成せずに、ターン間でコンテキストを維持できます。
import { Agent, run } from '@openai/agents';
const agent = new Agent({ name: 'Assistant', instructions: 'Reply very concisely.',});
async function main() { const first = await run(agent, 'What city is the Golden Gate Bridge in?'); console.log(first.finalOutput); // -> "San Francisco"
const previousResponseId = first.lastResponseId; const second = await run(agent, 'What state is it in?', { previousResponseId, }); console.log(second.finalOutput); // -> "California"}
main().catch(console.error);conversationId と previousResponseId は同時に使用できません。システム間で共有できる名前付きの会話リソースが必要な場合は conversationId を使い、あるレスポンスから次のレスポンスへ最小限のコストで継続するための SDK レベルの基本コンポーネントだけが必要な場合は previousResponseId を使ってください。
フックとカスタマイズ
Section titled “フックとカスタマイズ”モデル呼び出し入力フィルター
Section titled “モデル呼び出し入力フィルター”callModelInputFilter を使うと、モデルが呼び出される 直前 にモデル入力を編集できます。このフックは、現在のエージェント、コンテキスト、結合された入力項目(セッション履歴がある場合はそれも含む)を受け取ります。更新した input 配列と任意の instructions を返すことで、機密データのマスキング、古いメッセージの削除、追加のシステム指示の挿入を行えます。
runner.run(..., { callModelInputFilter }) で実行ごとに設定するか、Runner の設定(RunConfig の callModelInputFilter)でデフォルトとして設定します。
戻り値は ModelInputData オブジェクト、つまり { input: AgentInputItem[], instructions? } である必要があります。input フィールドは必須で、配列でなければなりません。それ以外の形式を返すと UserError がスローされます。
SDK は、フィルターを呼び出す前に、準備済みのターン入力を複製します。session も使用している場合は、フィルター処理後の複製が永続化されるため、ここで適用したマスキングや切り詰めは、保存されるセッション履歴にも反映されます。
繰り返されるモデル呼び出し間で処理結果をメモ化するために、フィルターがオブジェクトの同一性に依存している場合は、そのフィルターに preserveInputIdentity = true を設定します。これにより、SDK が準備した各項目が準備済み入力に残っている間、SDK はその項目の同一性を保持します。ただし、フィルターの各呼び出しに渡される配列は新しいものです。このオプションは、呼び出し元が最初に run() に渡したオブジェクトの同一性を保持するものではありません。
import { CallModelInputFilter, Runner } from '@openai/agents';
const inspectedItems = new WeakSet<object>();
const inspectInputOnce: CallModelInputFilter = ({ modelData }) => { for (const item of modelData.input) { if (item && typeof item === 'object' && !inspectedItems.has(item)) { inspectedItems.add(item); recordPreparedItem(item); } }
return modelData;};
// Keep SDK-prepared item identities stable across repeated model calls so the// WeakSet can recognize items that this filter already inspected. Do not mutate// the items or their nested values.inspectInputOnce.preserveInputIdentity = true;
const runner = new Runner({ callModelInputFilter: inspectInputOnce });
declare function recordPreparedItem(item: object): void;
export { runner };SDK は準備済みの項目やそのネストされた値を凍結しないため、このモードはオプトインです。フィルターと、フィルターが呼び出すすべてのヘルパーは、項目を不変として扱い、変更する代わりに置き換え用の値を返す必要があります。フィルターから戻った後も、モデルへのリクエストとセッション入力は、それぞれ切り離されたコピーのままです。
conversationId または previousResponseId を使用する場合、このフックは次の Responses API 呼び出し用に準備されたペイロードに対して実行されます。以前のサーバー管理のコンテキストは API が復元するため、その呼び出しでフィルター処理される配列は、過去の履歴全体ではなく、新しいターンの差分だけを表している場合があります。この最終フィルター処理の前に、保存済み履歴と現在のターンのマージ方法を変更する必要がある場合は、sessionInputCallback を使用してください。
ツールエラーフォーマッター
Section titled “ツールエラーフォーマッター”toolErrorFormatter を使うと、モデルに返されるツールエラーメッセージをカスタマイズできます。これにより、SDK のデフォルトメッセージではなく、ドメイン固有の文言(コンプライアンスに関する指針など)を返せます。
フォーマッターは、実行ごと(runner.run(..., { toolErrorFormatter }))に設定するか、RunConfig でグローバルに設定できます(new Runner(...) の toolErrorFormatter)。
このフォーマッターは、承認拒否に対するグローバルなフォールバックです。result.state.reject(interruption, { message: '...' }) で特定の中断を拒否した場合、その呼び出しごとの message が toolErrorFormatter より優先されます。どちらも指定されていない場合、SDK はデフォルトの拒否テキスト Tool execution was not approved. にフォールバックします。
このフォーマッターは、toolNotFoundBehavior: 'return_error_to_model' が、対応するツールの見つからない関数ツール呼び出しをモデルに見えるツール出力へ変換する際にも実行されます。この場合のデフォルトメッセージは Tool '<name>' not found. です。
フォーマッターは次の情報を受け取ります。
kind('approval_rejected'または'tool_not_found')toolType('function'、'computer'、'shell'、または'apply_patch')toolNamecallIddefaultMessage(現在のエラー種別に対する SDK のフォールバックメッセージ)runContext
メッセージをオーバーライドするには文字列を返し、SDK のデフォルトを維持するには undefined を返します。フォーマッターが例外をスローした場合(または文字列以外の値を返した場合)、SDK は警告を記録し、現在のエラー種別に対するデフォルトメッセージにフォールバックします。
推論項目の ID ポリシー
Section titled “推論項目の ID ポリシー”reasoningItemIdPolicy を使うと、SDK が以前に生成された実行項目を後続のモデル入力用の AgentInputItem[] に戻す際に、推論項目の id フィールドを保持するかどうかを制御できます。
これは、SDK が生成済みのモデル項目を再び入力として使用する、次のような箇所に影響します。
- 同じ実行内での後続のモデル呼び出し(ツール実行後など)
- 生成済みの項目を入力 / 履歴として再利用する後続のターン
- 保存済みの
RunStateから再開された実行 result.history/result.outputなどの派生した実行結果ビュー(モデル入力形式の配列)'preserve'(デフォルト)は推論項目の ID を保持します。'omit'は、推論項目を入力として返す前にidフィールドを取り除きます。- 推論項目以外には影響しません。
この設定で 変更されない ものは次のとおりです。
- モデルの元のレスポンス(
result.rawResponses) - 実行項目(
result.newItems) - プロバイダーが返した、モデルの現在のターンの出力
つまり、このポリシーは、SDK が過去に生成された項目から 次の入力 を構築する際に適用されます。
このポリシーは、実行ごと(runner.run(..., { reasoningItemIdPolicy: 'omit' }))に設定するか、ランナーのデフォルト(new Runner({ reasoningItemIdPolicy: 'omit', ... }))として設定できます。保存済みの RunState から再開する際は、オーバーライドしない限り、以前に確定したポリシーが再利用されます。
callModelInputFilter との関係
Section titled “callModelInputFilter との関係”reasoningItemIdPolicy は callModelInputFilter より前に適用されます。カスタムの動作が必要な場合でも、callModelInputFilter で準備済み入力を確認し、モデル呼び出しの前に推論 ID を手動で再追加または削除できます。
'omit' を使用する場面
Section titled “'omit' を使用する場面”再び入力として使用する推論項目を ID なしに正規化したい場合は、'omit' を使用してください(たとえば、転送または再利用するモデル入力をシンプルに保つ場合や、アプリのパイプラインの連携要件に合わせる場合)。
バックエンド / プロバイダーが、再び入力として使用された推論項目をリクエスト検証エラーで拒否する場合にも、トラブルシューティングの選択肢として有用です(たとえば、後続の入力の推論項目 ID に関連する HTTP 400 エラー)。そのような場合、'omit' を使って再利用する推論 ID を取り除くことで、バックエンドが新しいリクエストでは無効と見なす ID の送信を回避できます。
SDK に、再利用する入力全体で推論項目の ID を引き継がせたい場合で、連携先がその ID を受け入れる場合は、'preserve' を維持してください。
エラーと復旧
Section titled “エラーと復旧”エラーハンドラー
Section titled “エラーハンドラー”errorHandlers を使うと、サポートされているランタイムエラーをスローする代わりに、最終出力に変換できます。サポートされているキーは maxTurns、modelRefusal、invalidFinalOutput です。
errorHandlers.maxTurnsは、最大ターン数のエラーのみを処理します。errorHandlers.modelRefusalは、ModelRefusalErrorとして通知されるモデルの拒否を処理します。errorHandlers.invalidFinalOutputは、構造化された最終出力がない場合、または出力スキーマの検証に失敗した場合に発生するModelBehaviorErrorインスタンスを処理します。ハンドラーは、モデルをリトライしたり、ツールの副作用を再発生させたりすることなく、検証済みのフォールバックを返します。errorHandlers.defaultは、サポートされている種別のフォールバックとして使用されます。- ハンドラーは
{ error, context, runData }を受け取り、{ finalOutput, includeInHistory? }を返すことができます。返されるfinalOutputは、現在のエージェントのoutputTypeと一致する必要があります。structured outputs の場合、SDK は実行を完了する前にフォールバックを検証します。undefinedを返すと、そのエラーのデフォルトの動作が維持されます。
SDK は、キャッチできる少数のエラーをスローします。
MaxTurnsExceededError–maxTurnsへの到達ModelBehaviorError– モデルによる無効な出力の生成(不正な形式の JSON、不明なツールなど)ModelRefusalError– 要求された出力の生成をモデルが拒否ModelTimeoutError– リトライ処理後も、タイムアウトしたモデルリクエストの試行が最終的な失敗として残った状態InputGuardrailTripwireTriggered/OutputGuardrailTripwireTriggered– ガードレール違反ToolInputGuardrailTripwireTriggered/ToolOutputGuardrailTripwireTriggered– ツールガードレール違反GuardrailExecutionError– ガードレールの完了に失敗ToolTimeoutError–timeoutBehavior: 'raise_exception'を使用している関数ツールがtimeoutMsを超過ToolCallError– タイムアウト以外のエラーによる関数ツールの実行失敗UserError– 設定またはユーザー入力に基づいてスローされるエラー
すべて基底の AgentsError クラスを継承しており、現在の実行状態にアクセスするための state プロパティが提供される場合があります。
以下は、GuardrailExecutionError を処理するコード例です。入力ガードレールは最初のユーザー入力に対してのみ実行されるため、この例では元の入力とコンテキストで実行を再開しています。また、保存済みの状態を再利用し、モデルを再度呼び出すことなく出力ガードレールをリトライする方法も示しています。
import { Agent, GuardrailExecutionError, InputGuardrail, InputGuardrailTripwireTriggered, OutputGuardrail, OutputGuardrailTripwireTriggered, run,} from '@openai/agents';import { z } from 'zod';
// Shared guardrail agent to avoid re-creating it on every fallback run.const guardrailAgent = new Agent({ name: 'Guardrail check', instructions: 'Check if the user is asking you to do their math homework.', outputType: z.object({ isMathHomework: z.boolean(), reasoning: z.string(), }),});
async function main() { const input = 'Hello, can you help me solve for x: 2x + 3 = 11?'; const context = { customerId: '12345' };
// Input guardrail example
const unstableInputGuardrail: InputGuardrail = { name: 'Math Homework Guardrail (unstable)', execute: async () => { throw new Error('Something is wrong!'); }, };
const fallbackInputGuardrail: InputGuardrail = { name: 'Math Homework Guardrail (fallback)', execute: async ({ input, context }) => { const result = await run(guardrailAgent, input, { context }); const isMathHomework = result.finalOutput?.isMathHomework ?? /solve for x|math homework/i.test(JSON.stringify(input)); return { outputInfo: result.finalOutput, tripwireTriggered: isMathHomework, }; }, };
const agent = new Agent({ name: 'Customer support agent', instructions: 'You are a customer support agent. You help customers with their questions.', inputGuardrails: [unstableInputGuardrail], });
try { // Input guardrails only run on the first turn of a run, so retries must start a fresh run. await run(agent, input, { context }); } catch (e) { if (e instanceof GuardrailExecutionError) { console.error(`Guardrail execution failed (input): ${e}`); try { agent.inputGuardrails = [fallbackInputGuardrail]; // Retry from scratch with the original input and context. await run(agent, input, { context }); } catch (ee) { if (ee instanceof InputGuardrailTripwireTriggered) { console.log('Math homework input guardrail tripped on retry'); } else { throw ee; } } } else { throw e; } }
// Output guardrail example
const replyOutputSchema = z.object({ reply: z.string() });
const unstableOutputGuardrail: OutputGuardrail<typeof replyOutputSchema> = { name: 'Answer review (unstable)', execute: async () => { throw new Error('Output guardrail crashed.'); }, };
const fallbackOutputGuardrail: OutputGuardrail<typeof replyOutputSchema> = { name: 'Answer review (fallback)', execute: async ({ agentOutput }) => { const outputText = typeof agentOutput === 'string' ? agentOutput : (agentOutput?.reply ?? JSON.stringify(agentOutput)); const flagged = /math homework|solve for x|x =/i.test(outputText); return { outputInfo: { flaggedOutput: outputText }, tripwireTriggered: flagged, }; }, };
const agent2 = new Agent<unknown, typeof replyOutputSchema>({ name: 'Customer support agent (output check)', instructions: 'You are a customer support agent. Answer briefly.', outputType: replyOutputSchema, outputGuardrails: [unstableOutputGuardrail], });
try { await run(agent2, input, { context }); } catch (e) { if (e instanceof GuardrailExecutionError && e.state) { console.error(`Guardrail execution failed (output): ${e}`); try { agent2.outputGuardrails = [fallbackOutputGuardrail]; // Output guardrails can be retried using the saved state without another model call. await run(agent2, e.state); } catch (ee) { if (ee instanceof OutputGuardrailTripwireTriggered) { console.log('Output guardrail tripped after retry with saved state'); } else { throw ee; } } } else { throw e; } }}
main().catch(console.error);入力と出力のリトライの違いは次のとおりです。
- 入力ガードレールは、実行の最初のユーザー入力に対してのみ実行されるため、リトライするには同じ入力 / コンテキストで新しい実行を開始する必要があります。保存済みの
stateを渡しても、入力ガードレールは再実行されません。 - 出力ガードレールはモデルのレスポンス後に実行されるため、
GuardrailExecutionErrorの保存済みstateを再利用すると、モデルを再度呼び出さずに出力ガードレールを再実行できます。
上記の例を実行すると、次の出力が表示されます。
Guardrail execution failed (input): Error: Input guardrail failed to complete: Error: Something is wrong!Math homework input guardrail tripped on retryGuardrail execution failed (output): Error: Output guardrail failed to complete: Error: Output guardrail crashed.Output guardrail tripped after retry with saved state