エージェントの実行結果

エージェントの実行を行うと、次のいずれかを受け取ります:

RunResult — stream: true なしで run を呼び出した場合
StreamedRunResult — stream: true 付きで run を呼び出した場合。ストリーミングの詳細は、ストリーミングも参照してください。

どちらの実行結果型も、finalOutput、newItems、interruptions、state などの同じ主要な結果サーフェスを公開します。StreamedRunResult は、completed、toStream()、toTextStream()、currentAgent などのストリーミング制御を追加します。

適切な結果サーフェスの選択

ほとんどのアプリケーションで必要になるプロパティは数個だけです:

必要なもの	使用するもの
ユーザーに表示する最終回答	`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 スキーマが定義されている場合。出力は自動的にこのスキーマに基づいてパースされます
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、監査、デバッグ
`history`	`input + 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 は、実行中に何が起きたかを最もリッチに把握できます。一般的な項目型は次のとおりです:

RunMessageOutputItem — アシスタントメッセージ用
RunReasoningItem — 推論項目用
RunToolSearchCallItem と RunToolSearchOutputItem — Responses のツール検索リクエストと、それが返す読み込まれたツール定義用
RunToolCallItem と RunToolCallOutputItem — ツール呼び出しとその結果用
RunToolApprovalItem — 承認のために一時停止したツール呼び出し用
RunHandoffCallItem と RunHandoffOutputItem — ハンドオフリクエストと完了した移譲用

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

会話の継続または再開

アクティブなエージェント

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 を調べてください。

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

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 — 実行途中のアクティブなエージェントの追跡

ストリーミング実行の確定した最終状態が必要な場合は、finalOutput、history、interruptions、またはその他の要約プロパティを読む前に completed を待機してください。イベントごとの処理については、ストリーミングを参照してください。

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

診断と高度なフィールド

実行コンテキスト

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

元レスポンス

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

ガードレール結果

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

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

使用状況

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

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,
    });
  }
}