エージェントの実行結果

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

• stream: true なしで run を呼び出した場合は RunResult
• stream: true ありで run を呼び出した場合は StreamedRunResult。ストリーミングの詳細は ストリーミング も確認してください

どちらの結果タイプでも、finalOutput、newItems、interruptions、state など同じ中核的な結果サーフェスが提供されます。StreamedRunResult には、completed、toStream()、toTextStream()、currentAgent などのストリーミング制御が追加されます。

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

ほとんどのアプリケーションで必要なのは、いくつかのプロパティだけです:

必要なもの	使用するもの
ユーザーに表示する最終回答	finalOutput
完全なローカルトランスクリプトを含む、再生可能な次ターン入力	history
この実行で新規生成されたモデル形式アイテムのみ	output
エージェント / ツール / ハンドオフのメタデータを含む詳細な実行アイテム	newItems
通常、次のユーザーターンを処理すべきエージェント	lastAgent または activeAgent
OpenAI Responses API の previousResponseId 連鎖	lastResponseId
保留中の承認と再開可能スナップショット	interruptions と state
アプリコンテキスト、承認、使用量、ネストした agent-tool 入力	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 プロパティにユニオン型を提供できます。

例:

Handoff final output types

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 は、チャットライクなユースケースで完全な履歴を維持する便利な方法です:

History loop

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
• reasoning アイテム用の RunReasoningItem
• Responses のツール検索リクエストと、それが返すロード済みツール定義用の RunToolSearchCallItem および RunToolSearchOutputItem
• ツール呼び出しとその結果用の RunToolCallItem および RunToolCallOutputItem
• 承認待ちで一時停止したツール呼び出し用の RunToolApprovalItem
• ハンドオフ要求と完了済み転送用の RunHandoffCallItem および RunHandoffOutputItem

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

会話の継続または再開

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

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

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

割り込みと再開可能な state

ツールに承認が必要な場合、実行は一時停止し、interruptions に保留中の RunToolApprovalItem が入ります。これには、直接ツール、ハンドオフ後に到達したツール、ネストした agent.asTool() 実行で発生した承認が含まれる場合があります。

result.state.approve(...) / result.state.reject(...) で承認を処理し、同じ state を run() に戻して再開します。すべての割り込みを一度に解決する必要はありません。一部だけ処理して再実行した場合、解決済み呼び出しは継続でき、未解決のものは保留のままで再び実行を一時停止します。

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

サーバー管理の継続

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

すでに history、session、または conversationId で会話を継続している場合、通常 lastResponseId は不要です。マルチステップ実行のすべての元モデル応答が必要な場合は、代わりに rawResponses を確認してください。

ネストした agent-tool メタデータ

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

このネストしたコンテキストで agentToolInvocation が公開するもの:

• toolName
• toolCallId
• toolArguments

ネストした agent-tool 実行に渡された構造化入力も必要な場合は、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 からも利用できます。ストリーミング実行では、レスポンス到着に応じてこのデータが更新されます。

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