エージェントの実行結果

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

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

最終出力

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

string — outputType が未定義のエージェントのデフォルト
unknown — エージェントの出力型として JSON スキーマが定義されている場合。この場合、JSON は解析されていますが、型の検証は手動で行う必要があります
z.infer<outputType> — エージェントの出力型として Zod スキーマが定義されている場合。出力は自動的にこのスキーマで解析されます
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

次ターンの入力

次の 2 つの方法で、次ターン用の入力にアクセスできます:

result.history — あなたの入力とエージェントの出力の両方のコピーを含みます
result.output — エージェントのフル実行の出力を含みます

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?'));
}

最後のエージェント

lastAgent プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次回のユーザー入力時に有用です。たとえば、一次トリアージエージェントが言語別エージェントにハンドオフする場合、最後のエージェントを保存して、次回ユーザーがメッセージを送るときに再利用できます。

ストリーミングモードでは、現在実行中のエージェントに対応する currentAgent プロパティへアクセスするのも有用です。

新しいアイテム

newItems プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは RunItem です。ランアイテムは、LLM が生成した元アイテムをラップします。これにより、LLM の出力に加えて、これらのイベントがどのエージェントに関連付けられていたかにもアクセスできます。

RunMessageOutputItem は LLM からのメッセージを示します。元アイテムは生成されたメッセージです
RunHandoffCallItem は LLM がハンドオフツールを呼び出したことを示します。元アイテムは LLM からのツール呼び出しアイテムです
RunHandoffOutputItem はハンドオフが発生したことを示します。元アイテムはハンドオフツール呼び出しへのツール応答です。アイテムからソース/ターゲットエージェントにもアクセスできます
RunToolCallItem は LLM がツールを呼び出したことを示します
RunToolCallOutputItem はツールが呼び出されたことを示します。元アイテムはツールの応答です。アイテムからツール出力にもアクセスできます
RunReasoningItem は LLM からの推論アイテムを示します。元アイテムは生成された推論です
RunToolApprovalItem は LLM がツール呼び出しの承認を要求したことを示します。元アイテムは LLM からのツール呼び出しアイテムです

状態

state プロパティには、実行の状態が含まれます。result に付随するものの多くは state から導出されていますが、state はシリアライズ/デシリアライズ可能で、エラーからの復旧やinterruption への対応が必要な場合に、後続の run 呼び出しの入力としても使用できます。

中断

エージェントで needsApproval を使用している場合、続行前に処理が必要な interruptions が発生することがあります。その場合、interruptions は中断を引き起こした ToolApprovalItem の配列になります。中断への対処方法の詳細は、人間の介入（HITL）を参照してください。

その他の情報

元レスポンス

rawResponses プロパティには、エージェントの実行中にモデルが生成した元の LLM レスポンスが含まれます。

最後のレスポンス ID

lastResponseId プロパティには、エージェントの実行中にモデルが最後に生成したレスポンスの ID が含まれます。

ガードレールの結果

inputGuardrailResults と outputGuardrailResults プロパティには、ガードレールの結果（存在する場合）が含まれます。ガードレールの結果には、記録や保存に有用な情報が含まれることがあるため、利用できるようにしています。

ツールのガードレール結果は、toolInputGuardrailResults と toolOutputGuardrailResults で個別に公開されています。

使用状況

トークン使用量は result.state.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,
    });
  }
}

元の入力

input プロパティには、run メソッドに提供した元の入力が含まれます。多くの場合これは不要ですが、必要な場合に備えて利用できます。