トレーシング

Agents SDK には組み込みのトレーシング機能があり、エージェント実行中に発生するイベントの網羅的な記録を収集します。これには LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまでも含まれます。Traces ダッシュボードを使うと、開発時や本番環境でワークフローをデバッグ・可視化・モニタリングできます。

トレースとスパン

トレース (Trace) は「ワークフロー」の単一のエンドツーエンド操作を表します。トレースは Span で構成され、次のプロパティを持ちます
- workflow_name: 「コード生成」「カスタマーサービス」など、論理的なワークフローまたはアプリの名前
- trace_id: トレースの一意 ID。指定しない場合は自動生成されます。形式は trace_<32_alphanumeric>
- group_id: 会話の複数トレースをリンクするためのオプション ID。例としてチャットスレッド ID など
- disabled: true の場合、このトレースは記録されません
- metadata: トレースに付与する任意のメタデータ
スパン (Span) は開始時刻と終了時刻を持つ操作を表します
- started_at と ended_at のタイムスタンプ
- 所属するトレースを示す trace_id
- 親 Span を指す parent_id（存在する場合）
- span_data: Span の情報。たとえば AgentSpanData はエージェント情報、GenerationSpanData は LLM 生成情報など

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

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

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

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

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

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

既定の OpenAI Realtime API で RealtimeAgent と RealtimeSession を使用している場合、トレーシングは 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}`);
});

run の 2 回の呼び出しが withTrace() に包まれているため、それぞれが個別のトレースを作らず、全体のトレースに含まれます

トレースの作成

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

現在のトレースは Node.js の AsyncLocalStorage またはそれに相当するポリフィルで追跡されるため、並行実行時にも自動で機能します。

スパンの作成

createGenerationSpan() や createFunctionSpan() などの create*Span() メソッドでスパンを作成できます。通常は手動で作成する必要はありません。独自のスパンを追跡したい場合は createCustomSpan() が利用できます。

スパンは自動的に現在のトレースに属し、最も近い親スパンの下にネストされます。これは Node.js の AsyncLocalStorage または対応するポリフィルで管理されています。

機微なデータ

一部のスパンは機微なデータを含む可能性があります。

createGenerationSpan() は LLM 生成の入出力を、createFunctionSpan() は関数呼び出しの入出力を保存します。機微なデータを含む場合があるため、RunConfig.traceIncludeSensitiveData で保存を無効化できます。

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

トレーシングの高レベルアーキテクチャは次のとおりです。

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

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

addTraceProcessor()
デフォルトの処理に追加して、準備が整ったトレースやスパンを受け取る独自のトレースプロセッサを追加します。これにより、OpenAI バックエンドに送信しつつ独自処理を行えます。
setTraceProcessors()
デフォルトのプロセッサを置換し、独自のトレースプロセッサのみを使用します。OpenAI バックエンドへは TracingProcessor を含めない限り送信されません。