エージェントの実行

エージェントはそれ自体では何も行いません。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 runner
const 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 のライフサイクルと設定

エージェントループ

Runner の run メソッドを使用する際は、開始エージェントと入力を渡します。入力には、ユーザーメッセージとして扱われる文字列、または OpenAI Responses API のアイテムである入力アイテムのリストを指定できます。

その後、ランナーは次のループを実行します。

現在の入力を使用して、現在のエージェントのモデルを呼び出します。
LLM のレスポンスを確認します。
- 最終出力 → 返します。
- ハンドオフ → 新しいエージェントに切り替え、蓄積された会話履歴を維持して、手順 1 に戻ります。
- ツール呼び出し → ツールを実行し、その実行結果を会話に追加して、手順 1 に戻ります。
maxTurns が null でない限り、maxTurns に達すると MaxTurnsExceededError をスローします。

Runner のライフサイクル

アプリの起動時に Runner を作成し、複数のリクエストで再利用してください。このインスタンスには、モデルプロバイダーやトレーシングオプションなどのグローバル設定が保存されます。完全に異なる設定が必要な場合にのみ、別の Runner を作成してください。シンプルなスクリプトでは、内部でデフォルトランナーを使用する run() を呼び出すこともできます。

実行引数

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'` を使用します。
`errorHandlers`	–	サポートされるランタイムエラーのハンドラーです。エラーハンドラーを参照してください。
`conversationId`	–	サーバー側の会話を再利用します（OpenAI Responses API と Conversations API のみ）。
`previousResponseId`	–	会話を作成せずに、以前の Responses API 呼び出しから続行します（OpenAI Responses API のみ）。

ストリーミング

ストリーミングを使用すると、LLM の実行中にストリーミングイベントも受信できます。ストリームが開始されると、StreamedRunResult には、生成されたすべての新しい出力を含む実行の完全な情報が格納されます。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'` はモデルから確認できるツールエラーを返して実行を継続します。

toolExecution.maxFunctionToolConcurrency は、1 以上の整数である必要があります。この設定は、ローカル関数ツールの SDK 側での実行のみを制限します。プロバイダー側の modelSettings.parallelToolCalls は変更しません。

toolExecution.preApprovalInputGuardrails はデフォルトで無効です。true に設定すると、承認を必要とするローカル関数ツールは、SDK が保留中の承認による中断を記録する前に入力ガードレールを実行します。ガードレールが rejectContent を返すと、SDK は承認を求める代わりに、その拒否メッセージをツール出力として返します。ガードレールが呼び出しを許可した場合も承認リクエストは発生し、承認の解決後、ツールの実行直前に同じ入力ガードレールが再度実行されます。

状態と会話の管理

メモリ戦略の選択

次のターンに状態を引き継ぐ一般的な方法は 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、またはスナップショットを使用します。ワークスペースのライフサイクルについては、コンセプトを参照してください。

会話 / チャットスレッド

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"

対話型のバージョンについては、チャットのコード例を参照してください。

サーバー管理の会話

ターンごとにローカルの会話履歴全体を送信する代わりに、OpenAI Responses API に会話履歴を永続化させることができます。これは、長い会話や複数のサービスを連携させる場合に便利です。以下のいずれかのサーバー管理方式では、各リクエストで新しいターンの入力のみを渡します。API が以前の状態を再利用します。詳細については、会話状態ガイドを参照してください。

OpenAI では、サーバー側の状態を再利用する方法を 2 つ提供しています。

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`

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 を使用します。

フックとカスタマイズ

モデル入力フィルターの呼び出し

モデルが呼び出される直前にモデル入力を編集するには、callModelInputFilter を使用します。このフックは、現在のエージェント、コンテキスト、および統合された入力アイテム（存在する場合はセッション履歴を含む）を受け取ります。機密データの編集、古いメッセージの削除、追加のシステムガイダンスの挿入を行うには、更新された input 配列と任意の instructions を返します。

実行ごとに runner.run(..., { callModelInputFilter }) で設定するか、Runner の設定（RunConfig の callModelInputFilter）でデフォルトとして設定します。

戻り値は、{ input: AgentInputItem[], instructions? } という ModelInputData オブジェクトである必要があります。input フィールドは必須で、配列でなければなりません。それ以外の形式を返すと、UserError がスローされます。

SDK は、フィルターを呼び出す前に、準備されたターン入力を複製します。session も使用している場合は、フィルター処理された複製が永続化されるため、ここで適用された編集や切り詰めは、保存されたセッション履歴にも反映されます。

conversationId または previousResponseId を使用する場合、このフックは次の Responses API 呼び出し用に準備されたペイロードに対して実行されます。以前のサーバー管理コンテキストは API によって復元されるため、その呼び出しのフィルター処理対象の配列には、以前の履歴全体ではなく、新しいターンの差分のみがすでに含まれている場合があります。この最終フィルター処理の前に、保存された履歴と現在のターンをマージする方法を変更する必要がある場合は、sessionInputCallback を使用します。

ツールエラーフォーマッター

モデルに返されるツールエラーメッセージをカスタマイズするには、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'）
toolName
callId
defaultMessage（現在のエラー種別に対する SDK のフォールバックメッセージ）
runContext

メッセージを上書きするには文字列を返し、SDK のデフォルトを維持するには undefined を返します。フォーマッターが例外をスローした場合（または文字列以外の値を返した場合）、SDK は警告をログに記録し、現在のエラー種別に対するデフォルトメッセージにフォールバックします。

推論アイテムの ID ポリシー

SDK が以前に生成された実行アイテムを後続のモデル入力用の AgentInputItem[] に戻す際に、推論アイテムの id フィールドを保持するかどうかを制御するには、reasoningItemIdPolicy を使用します。

これは、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` との相互作用

reasoningItemIdPolicy は callModelInputFilter より前に適用されます。カスタム動作が必要な場合、callModelInputFilter では、準備された入力を引き続き確認し、モデル呼び出しの前に推論 ID を手動で再追加または削除できます。

`'omit'` の使用場面

再利用される推論アイテムを ID なしで正規化する場合（転送または再利用するモデル入力を簡潔に保つ場合や、アプリのパイプラインにおける連携要件に合わせる場合など）は、'omit' を使用します。

バックエンドまたはプロバイダーが、再利用された推論アイテムをリクエスト検証エラー（後続入力内の推論アイテム ID に関連する HTTP 400 エラーなど）で拒否する場合にも、トラブルシューティングの選択肢として役立ちます。このような場合、'omit' で再利用される推論 ID を削除すると、バックエンドが新しいリクエストに対して無効と判断する ID の送信を回避できます。

SDK で再利用される入力に推論アイテム ID を引き継ぎ、連携先がそれを受け入れる場合は、'preserve' を維持してください。

エラーと復旧

エラーハンドラー

サポートされるランタイムエラーを、スローする代わりに最終出力へ変換するには、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 – モデルが要求された出力の生成を拒否
InputGuardrailTripwireTriggered / OutputGuardrailTripwireTriggered – ガードレール違反
ToolInputGuardrailTripwireTriggered / ToolOutputGuardrailTripwireTriggered – ツールのガードレール違反
GuardrailExecutionError – ガードレールを完了できなかった場合
ToolTimeoutError – 関数ツールが timeoutMs を超過し、timeoutBehavior: 'raise_exception' を使用
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 retry
Guardrail execution failed (output): Error: Output guardrail failed to complete: Error: Output guardrail crashed.
Output guardrail tripped after retry with saved state