エージェントの実行結果

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

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

どちらの実行結果型も、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() を使用する場合、通常のツール呼び出しが発生する前にどの遅延ツールや名前空間が読み込まれたかを確認するには、これらのツール検索項目が最も簡単です。

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

会話の継続または再開

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

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 からも利用できます。ストリーミング実行では、このデータはレスポンスの到着に応じて更新されます。

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