トレーシング

Agents SDK にはトレーシング機能が組み込まれており、エージェント実行中に発生するイベント（ LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで）を網羅的に記録します。
Traces ダッシュボードを使用すると、開発中および本番環境でワークフローをデバッグ・可視化・監視できます。

エクスポートループのライフサイクル

ほとんどの環境では、トレースは一定間隔で自動的にエクスポートされます。しかしブラウザや Cloudflare Workers では、この機能はデフォルトで無効化されています。キューに溜まり過ぎた場合にはエクスポートされますが、定期的には行われません。その場合、コードのライフサイクル内で getGlobalTraceProvider().forceFlush() を呼び出して手動でエクスポートしてください。

たとえば Cloudflare Worker では、コードを try/catch/finally ブロックでラップし、waitUntil と併用して forceFlush を呼び出すことで、ワーカー終了前にトレースを確実にエクスポートできます。

import { getGlobalTraceProvider } from '@openai/agents';

export default {
  async fetch(request, env, ctx): Promise<Response> {
    try {
      // your agent code here
      return new Response(`success`);
    } catch (error) {
      console.error(error);
      return new Response(String(error), { status: 500 });
    } finally {
      // make sure to flush any remaining traces before exiting
      ctx.waitUntil(getGlobalTraceProvider().forceFlush());
    }
  },
};

トレースとスパン

トレース は 1 つの「ワークフロー」のエンドツーエンドの操作を表し、スパンで構成されます。主なプロパティは次のとおりです:
- workflow_name : 論理的なワークフローやアプリ名。例: “Code generation” や “Customer service”
- trace_id : トレースの一意 ID。指定しない場合は自動生成。形式は trace_<32_alphanumeric>
- group_id : 省略可。同一会話内の複数トレースを紐付ける ID。例としてチャットスレッド ID など
- disabled : true の場合、このトレースは記録されません
- metadata : トレースに付与する追加メタデータ
スパン は開始時刻と終了時刻を持つ操作を表します。主なプロパティは次のとおりです:
- started_at と ended_at タイムスタンプ
- 所属するトレースを示す trace_id
- 親スパンを示す parent_id （存在する場合）
- span_data : スパンに関する情報。たとえば AgentSpanData はエージェント情報、GenerationSpanData は LLM 生成情報など

デフォルトのトレーシング

デフォルトで SDK は以下をトレースします。

run() または Runner.run() 全体を Trace でラップ
エージェントが実行されるたびに AgentSpan でラップ
LLM 生成を GenerationSpan でラップ
関数ツール呼び出しを FunctionSpan でラップ
ガードレールを GuardrailSpan でラップ
ハンドオフを HandoffSpan でラップ

トレース名はデフォルトで “Agent workflow” です。withTrace を使用して名前を設定するか、RunConfig.workflowName で名前やその他プロパティを設定できます。

さらに、カスタムトレーシングプロセッサーを設定して別の宛先へトレースを送信（置き換えや追加送信）することも可能です。

音声エージェントのトレーシング

RealtimeAgent と RealtimeSession を OpenAI Realtime API のデフォルト設定で使用する場合、トレーシングは Realtime API 側で自動的に行われます。RealtimeSession で tracingDisabled: true を指定するか、環境変数 OPENAI_AGENTS_DISABLE_TRACING を設定すると無効化できます。

詳細は音声エージェントの概要を参照してください。

上位レベルのトレース

複数回の run() 呼び出しを 1 つのトレースにまとめたい場合は、コード全体を withTrace() でラップします。

import { Agent, run, withTrace } from '@openai/agents';

const agent = new Agent({
  name: 'Joke generator',
  instructions: 'Tell funny jokes.',
});

await withTrace('Joke workflow', async () => {
  const result = await run(agent, 'Tell me a joke');
  const secondResult = await run(
    agent,
    `Rate this joke: ${result.finalOutput}`,
  );
  console.log(`Joke: ${result.finalOutput}`);
  console.log(`Rating: ${secondResult.finalOutput}`);
});

2 回の run 呼び出しが withTrace() でラップされているため、それぞれが個別のトレースを作成せず、全体トレースに含まれます。

トレースの作成

withTrace() 関数を使用してトレースを作成できます。あるいは getGlobalTraceProvider().createTrace() でトレースを手動作成し、withTrace() に渡すことも可能です。

現在のトレースは Node.js の AsyncLocalStorage（および各環境のポリフィル）で管理されるため、並行実行でも自動的に動作します。

スパンの作成

create*Span()（例: createGenerationSpan()、createFunctionSpan() など）メソッドでスパンを作成できますが、通常は手動で作成する必要はありません。カスタムスパン情報を追跡するために createCustomSpan() も利用できます。

スパンは現在のトレースに自動的に紐付けられ、最近のスパンを親としてネストされます。この仕組みも Node.js の AsyncLocalStorage で実装されています。

機微データ

特定のスパンでは機微データが記録される可能性があります。

createGenerationSpan() は LLM 生成の入出力を、createFunctionSpan() は関数呼び出しの入出力を保存します。これらに機微データが含まれる場合は、RunConfig.traceIncludeSensitiveData で記録を無効化できます。

カスタムトレーシングプロセッサー

トレーシングの高レベル構成は以下のとおりです。

初期化時にグローバル TraceProvider を作成し、getGlobalTraceProvider() からアクセス
TraceProvider には BatchTraceProcessor を設定し、バッチで OpenAITracingExporter にトレース／スパンを送信
OpenAITracingExporter が OpenAI バックエンドへバッチ送信

このデフォルト構成をカスタマイズし、他のバックエンドへトレースを送信したりエクスポーター挙動を変更したりするには次の 2 つの方法があります。

addTraceProcessor()
既存構成に追加でトレースプロセッサーを追加します。OpenAI バックエンドへ送信しつつ、独自処理も行いたい場合に使用します。
setTraceProcessors()
デフォルトのプロセッサーを 置き換え ます。OpenAI バックエンドへ送信したい場合は、その機能を持つ TracingProcessor を含めてください。