コンテンツにスキップ

エージェントの実行結果

エージェントの実行では、次のいずれかが返されます。

  • stream: true を指定せずに run を呼び出した場合は RunResult
  • stream: true を指定して run を呼び出した場合は StreamedRunResult。ストリーミングの詳細については、ストリーミングも参照してください。

どちらの実行結果型も、finalOutput、newItems、interruptions、state など、同じ主要な実行結果プロパティを公開しています。StreamedRunResult には、completed、toStream()、toTextStream()、currentAgent といったストリーミング用の制御機能が追加されています。

適切な実行結果プロパティの選択

Section titled “適切な実行結果プロパティの選択”

ほとんどのアプリケーションでは、少数のプロパティだけで十分です。

必要な情報や用途使用するプロパティ
ユーザーに表示する最終回答finalOutput
ローカルの完全な会話履歴を含む、再利用可能な次のターンの入力history
この実行で新たに生成されたモデル形式の項目のみoutput
エージェント、ツール、ハンドオフのメタデータを含む詳細な実行項目newItems
通常、次のユーザーターンを処理すべきエージェントlastAgent または activeAgent
previousResponseId を使用した OpenAI Responses API の連鎖lastResponseId
承認待ちの項目と再開可能なスナップショットinterruptions と state
アプリケーションのコンテキスト、承認、使用量、ネストされたエージェントツールへの入力runContext
現在のネストされた Agent.asTool() 呼び出しに関するメタデータ(たとえば customOutputExtractor 内で使用)agentToolInvocation
元のモデル呼び出しやガードレールの診断情報rawResponses とガードレールの結果配列

finalOutput プロパティには、最後に実行されたエージェントの最終出力が含まれます。この実行結果は、次のいずれかになります。

  • string — outputType が定義されていないエージェントのデフォルト
  • unknown — 出力型として JSON スキーマが定義されている場合。この場合、JSON は解析済みですが、型は手動で検証する必要があります。
  • z.infer<outputType> — 出力型として Zod スキーマが定義されている場合。出力はこのスキーマに基づいて自動的に解析されます。
  • 推論された検証出力型 — 出力型としてサポート対象の Standard Schema 値が定義されている場合。出力はこのスキーマに基づいて同期的に解析および検証されます。
  • undefined — エージェントが出力を生成しなかった場合(たとえば、出力を生成する前に停止した場合)

ストリーミング実行がまだ進行中の場合や、最終出力に到達する前に承認による中断で実行が一時停止した場合も、finalOutput は undefined になります。

異なる出力型を持つエージェント間でハンドオフを使用する場合は、new Agent() コンストラクターではなく Agent.create() メソッドでエージェントを作成してください。

これにより、SDK は起こり得るすべてのハンドオフ先の出力型を推論し、finalOutput プロパティにユニオン型を提供できます。

例:

ハンドオフの最終出力型
import { Agent, run } from '@openai/agents';
import { z } from 'zod';
const refundAgent = new Agent({
name: 'Refund Agent',
instructions:
'You are a refund agent. You are responsible for refunding customers.',
outputType: z.object({
refundApproved: z.boolean(),
}),
});
const orderAgent = new Agent({
name: 'Order Agent',
instructions:
'You are an order agent. You are responsible for processing orders.',
outputType: z.object({
orderId: z.string(),
}),
});
const triageAgent = Agent.create({
name: 'Triage Agent',
instructions:
'You are a triage agent. You are responsible for triaging customer issues.',
handoffs: [refundAgent, orderAgent],
});
const result = await run(triageAgent, 'I need to a refund for my order');
const output = result.finalOutput;
// ^? { refundApproved: boolean } | { orderId: string } | string | undefined

これらのプロパティは、それぞれ異なる用途に対応します。

プロパティ含まれる内容適した用途
inputこの実行のベースとなる入力。ハンドオフ入力フィルターによって履歴が書き換えられた場合は、実行の継続に使用されたフィルター適用後の入力が反映されます。この実行で実際に使用された入力の監査
outputこの実行で生成されたモデル形式の項目のみ。エージェントのメタデータは含まれません。モデルが新たに生成した差分のみの保存や再利用
newItemsエージェント、ツール、ハンドオフのメタデータを含む詳細な RunItem ラッパー。ログ、UI、監査、デバッグ
historyinput + newItems から構築された、再利用可能な次のターンの入力。手動のチャットループとクライアント側で管理する会話状態

実際の使い分けは次のとおりです。

  • アプリケーションで会話全体を手動で引き継ぐ場合は、history を使用します。
  • 過去の履歴をすでに別の場所に保存していて、この実行で新たに生成された項目のみが必要な場合は、output を使用します。
  • エージェントとの関連付け、ツールの出力、ハンドオフの境界、承認項目が必要な場合は、newItems を使用します。
  • conversationId または previousResponseId を使用している場合、通常は history を run() に戻しません。代わりに、新しいユーザー入力のみを渡し、サーバーが管理する ID を再利用します。詳しい比較については、エージェントの実行を参照してください。

history は、チャットのようなユースケースで完全な履歴を維持するのに便利です。

履歴ループ
import { Agent, user, run } from '@openai/agents';
import type { AgentInputItem } from '@openai/agents';
const agent = new Agent({
name: 'Assistant',
instructions:
'You are a helpful assistant knowledgeable about recent AGI research.',
});
let history: AgentInputItem[] = [
// initial message
user('Are we there yet?'),
];
for (let i = 0; i < 10; i++) {
// run 10 times
const result = await run(agent, history);
// update the history to the new output
history = result.history;
history.push(user('How about now?'));
}

newItems は、実行中に起きたことを最も詳しく把握できるプロパティです。主な項目の型は次のとおりです。

どのエージェントが項目を生成したか、あるいはその項目がツール、ツール検索、ハンドオフ、承認の境界を示しているかを知る必要がある場合は、output ではなく newItems を選んでください。toolSearchTool() を使用する場合、これらのツール検索項目を確認するのが、通常のツール呼び出しの前にどの遅延読み込みツールや名前空間が読み込まれたかを調べる最も簡単な方法です。

ローカルツールまたは MCP サーバーで customDataExtractor が定義されている場合、対応する RunToolCallOutputItem.customData には、返された SDK 専用のメタデータが含まれます。このデータは、レンダラー向けのヒントや内部 ID など、アプリケーションの UI 状態に役立ちます。RunState をシリアライズしても保持されますが、history には含まれず、モデルにも送り返されません。

RunToolCallOutputItem.output は、SDK 側のツールの戻り値です。JSON 互換のプリミティブ値、配列、プレーンオブジェクトは、RunState をシリアライズしても構造が保持されます。その他の実行時の値には、従来どおり文字列へのフォールバックが適用されます。このラッパーの値は、history や再利用時に使用されるモデル向けのツール出力である rawItem.output とは別のものです。

lastAgent プロパティには、最後に実行されたエージェントが含まれます。ハンドオフ後の次のユーザーターンでは、多くの場合、このエージェントを再利用するのが最適です。activeAgent は、同じ値のエイリアスです。

ストリーミングモードでは、実行の進行中に currentAgent で現在アクティブなエージェントを確認できます。

ツールに承認が必要な場合、実行は一時停止し、interruptions に承認待ちの RunToolApprovalItem が含まれます。これには、直接呼び出されたツール、ハンドオフ後に呼び出されたツール、ネストされた agent.asTool() の実行で発生した承認要求が含まれることがあります。

result.state.approve(...) / result.state.reject(...) で承認要求を処理してから、同じ state を run() に戻して実行を再開します。すべての中断を一度に処理する必要はありません。一部の項目だけを処理して再実行した場合、処理済みの呼び出しは続行できますが、未処理の呼び出しは保留のままとなり、実行が再び一時停止します。

state プロパティは、実行結果の基盤となるシリアライズ可能なスナップショットです。人間の介入(HITL)、再試行フロー、その他、一時停止した実行を後で再開する必要がある場合に使用します。

lastResponseId は、OpenAI Responses API の連鎖を使用する場合に、次のターンで previousResponseId として渡す値です。

すでに history、session、conversationId のいずれかで会話を継続している場合、通常は lastResponseId は必要ありません。複数ステップの実行で得られた元のモデルレスポンスをすべて確認する必要がある場合は、代わりに rawResponses を調べてください。

ネストされたエージェントツールのメタデータ

Section titled “ネストされたエージェントツールのメタデータ”

agentToolInvocation は、ネストされた Agent.asTool() の実行結果に使用するもので、特に customOutputExtractor 内で現在のツール呼び出しに関するメタデータが必要な場合に役立ちます。「実行全体が完了した」ことを示す汎用的なサマリーフィールドではありません。

このネストされたコンテキストでは、agentToolInvocation は次の情報を公開します。

  • toolName
  • toolCallId
  • toolArguments

ネストされたエージェントツールの実行に渡された構造化入力も必要な場合は、result.runContext.toolInput と組み合わせて使用してください。

通常のトップレベルの run() の実行結果では、これは通常 undefined です。このメタデータは実行時にのみ存在し、RunState にはシリアライズされません。関連するパターンについては、Agents as toolsを参照してください。

StreamedRunResult は、上記と同じ実行結果プロパティを継承しますが、ストリーミング固有の制御機能が追加されています。

  • アシスタントのテキストのみを取得する toTextStream()
  • イベントストリーム全体を取得する toStream() または for await ... of stream
  • 実行とすべての後処理コールバックの完了を待つ completed
  • ストリーミングの最終状態を確認する error と cancelled
  • 実行中にアクティブなエージェントを追跡する currentAgent
  • 実際にリクエストの実行段階まで到達したモデルターン数を確認する currentTurn
  • このストリーミング実行に適用された上限を確認する maxTurns(null は上限なしを意味します)

currentTurn は、モデルリクエストの実行が許可されたときにのみ増加します。最大ターン数のチェックや、実行をブロックする入力ガードレールによってリクエストが阻止された場合は増加せず、再開された実行では RunState に保持されたカウントから始まります。

ストリーミング実行の確定した最終状態が必要な場合は、completed を待ってから finalOutput、history、interruptions などのサマリープロパティを読み取ってください。イベントごとの処理については、ストリーミングを参照してください。

ストリーミング実行がキャンセルされた場合でも、クリーンアップ後に completed は正常に解決され、cancelled は true になります。ただし、現在のターンが完了していないため、finalOutput などのターン終了時のフィールドは未設定のままになることがあります。新しいユーザーメッセージを追加するのではなく、result.state(セッションを使用している場合は同じ session も)を使って、その未完了のターンを再開してください。

runContext プロパティは、実行結果から実行コンテキストにアクセスするための、サポート対象の公開インターフェースです。result.runContext.context はアプリケーションのコンテキストであり、同じ runContext オブジェクトには、承認、使用量、ネストされた toolInput など、SDK が管理する実行時メタデータも含まれます。全体の構造については、コンテキスト管理を参照してください。

rawResponses には、実行中に収集された元のモデルレスポンスが含まれます。ハンドオフやツールとモデルのサイクルの繰り返しなど、複数ステップの実行では複数のレスポンスが生成されることがあります。

実行を終了させる関数ツールの結果が出力ガードレールによって拒否された場合、SDK は、SDK が管理するほかの再利用用データとともに、rawResponses 内の現在のレスポンスをサニタイズします。拒否された最終的なツール出力を、このプロパティから引き続き確認できるとは考えないでください。情報を除去する範囲と制限については、拒否された最終的なツール出力を参照してください。

各レスポンスには、プロバイダーのリクエスト識別子が利用可能な場合、requestId が含まれることもあります。OpenAI Responses および Chat Completions のモデルは、ストリーミングと非ストリーミングの HTTP リクエストでこの値を設定します。ただし、一部のプロバイダーやトランスポートでは公開されないため、オプションとして扱ってください。

Chat Completions のテキスト出力では、正規化された output_text パートの providerData.annotations を調べることで、引用元の URL を読み取れます。非ストリーミングのレスポンスでは、プロバイダーのメッセージのアノテーションが保持されます。ストリーミングのレスポンスでは、テキストとともに受信した有効な url_citation アノテーションを保持し、重複する引用を除去し、不正な形式やサポートされていない形式のアノテーションを無視します。

Chat Completions の音声については、正規化されたモデルレスポンスは、音声のみのアシスタントメッセージを audio コンテンツパートで表します。そのメッセージが実行項目になった場合は、RunMessageOutputItem.rawItem で同じパートを確認できます。非ストリーミングのレスポンスに音声とともにテキストや拒否応答が含まれる場合、正規化されたアシスタントメッセージにはテキストまたは拒否応答が保持され、プロバイダーの完全なレスポンスは引き続き rawResponses[].providerData から取得できます。ストリーミングで複数形式の出力が混在する場合、プロバイダーの音声チャンクを到着時に取得する必要があれば、元のモデルストリームイベントを調べてください。完了後の rawResponses エントリーには、正規化されたテキストまたは拒否応答は含まれますが、再構成された音声は含まれません。ストリーミングの toTextStream() ヘルパーは、テキストのみを出力します。

modelSettings.preserveRawUsage が true の場合、完了した各レスポンスは rawUsage も公開できます。これは、SDK による正規化の前に取得された、元のデータから独立した JSON 互換のスナップショットです。正規化された Usage は引き続き response.usage から取得できます。rawUsage は、プロバイダー固有のフィールド名や、値が省略されているか明示的に指定されているかの違いを、提供された情報に基づいて保持します。プロバイダーが使用量を省略した場合や、ペイロードを安全にコピーできない場合は、undefined になることがあります。rawUsage は実行時にのみ存在し、シリアライズされた RunState からは意図的に省略されるため、実行を永続化して再開する前に、必要なフィールドをコピーしてください。

inputGuardrailResults と outputGuardrailResults プロパティには、エージェントレベルのガードレールの結果が含まれます。ツールのガードレールの結果は、toolInputGuardrailResults と toolOutputGuardrailResults を通じて別途公開されます。

ガードレールの判定をログに記録したり、ガードレール関数が返す追加のメタデータを確認したり、実行がブロックされた理由をデバッグしたりする場合は、これらの配列を使用してください。

実行を終了させる関数ツールの結果が拒否された場合、SDK は現在のレスポンスのガードレールメタデータを意図的にサニタイズします。outputGuardrailResults では、agentOutput が Output withheld by an output guardrail. になり、outputInfo は削除されます。現在の toolOutputGuardrailResults は判定を保持しますが、outputInfo を省略し、rejectContent の結果では同じプレースホルダーをメッセージとして使用します。過去に受け入れられた結果は変更されません。

あるガードレールの実行が失敗しても、同時に実行されたほかのガードレールのうち、正常に完了したものの結果は実行状態に残ります。ストリーミング実行では、completed が拒否された後に結果配列を確認してください。非ストリーミング実行では、GuardrailExecutionError に同じ確定済みの state が含まれます。

トークン使用量は result.state.usage に集計され、この実行のリクエスト数とトークン総数が追跡されます。同じ使用量オブジェクトは、result.runContext.usage からも取得できます。ストリーミング実行では、レスポンスの到着に合わせてこのデータが更新されます。

ストリーミングか非ストリーミングかにかかわらず、完了した Chat Completions の呼び出しは、プロバイダーが使用量オブジェクトを省略した場合でも 1 件のリクエストとしてカウントされます。その場合、プロバイダーがトークン数を報告していないため、トークン総数はゼロのままになります。

RunState からの使用量の読み取り
import { Agent, run } from '@openai/agents';
const agent = new Agent({
name: 'Usage Tracker',
instructions: 'Summarize the latest project update in one sentence.',
});
const result = await run(
agent,
'Summarize this: key customer feedback themes and the next product iteration.',
);
const usage = result.state.usage;
console.log({
requests: usage.requests,
inputTokens: usage.inputTokens,
outputTokens: usage.outputTokens,
totalTokens: usage.totalTokens,
});
if (usage.requestUsageEntries) {
for (const entry of usage.requestUsageEntries) {
console.log('request', {
endpoint: entry.endpoint,
inputTokens: entry.inputTokens,
outputTokens: entry.outputTokens,
totalTokens: entry.totalTokens,
});
}
}