トレーシング

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

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

サポートされているサーバーランタイムでは、トレースは定期的にエクスポートされます。Cloudflare Workers を含む一部のランタイムでは、トレーシング自体は有効なままですが、自動エクスポートループは利用できません。こうした環境では、ランタイムが破棄される前にキューに入ったトレースをエクスポートするため、リクエストライフサイクルの一部として getGlobalTraceProvider().forceFlush() を呼び出す必要があります。

このガイダンスはブラウザーには適用されません。ブラウザーではトレーシングがデフォルトで無効だからです。

たとえば、Cloudflare Worker では、コードを try/catch/finally ブロックでラップし、worker が終了する前にトレースが確実にエクスポートされるよう、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());
    }
  },
};

トレースとスパン

トレース は、「ワークフロー」の単一のエンドツーエンド操作を表します。トレースはスパンで構成されます。トレースには次のプロパティがあります。
- workflow_name: 論理的なワークフローまたはアプリです。たとえば「コード生成」や「カスタマーサービス」です。
- 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 で名前やその他のプロパティを設定できます。

さらに、カスタムトレーシングプロセッサーを設定すると、トレースを別の送信先へ送信できます（置き換え先、または副次的な送信先として）。

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

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

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

上位レベルのトレース

複数の run() 呼び出しを単一のトレースの一部にしたい場合があります。コード全体を 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() でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体トレースの一部になります。

トレースの作成

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

現在のトレースは、Node.js AsyncLocalStorage または各環境の polyfill を介して追跡されます。つまり、並行処理でも自動的に機能します。

スパンの作成

各種 create*Span()（例: createGenerationSpan()、createFunctionSpan() など）メソッドを使用してスパンを作成できます。一般的には、手動でスパンを作成する必要はありません。カスタムスパン情報を追跡するために、createCustomSpan() 関数を利用できます。

スパンは自動的に現在のトレースの一部になり、最も近い現在のスパンの下にネストされます。現在のスパンは、Node.js AsyncLocalStorage または各環境の polyfill を介して追跡されます。

機密データ

一部のスパンは、機密である可能性のあるデータをキャプチャする場合があります。

createGenerationSpan() は LLM 生成の入力/出力を保存し、 createFunctionSpan() は関数呼び出しの入力/出力を保存します。これらには機密データが含まれる可能性があるため、 RunConfig.traceIncludeSensitiveData を介して、そのデータのキャプチャを無効にできます。

OpenAI トレーシングエクスポーター

サポートされているサーバーランタイムでは、デフォルトのトレーシング設定によってすでに OpenAI にエクスポートされます。トレースのエクスポートで OPENAI_API_KEY とは異なる認証情報を使用する必要がある場合は、setTracingExportApiKey() を使用してください。

カスタムの取り込み動作が必要な場合は、 OpenAITracingExporter を自分でインスタンス化し、setTraceProcessors(...) または addTraceProcessor(...) でインストールしてください。このエクスポーターは、apiKey、endpoint、organization、project、maxRetries、baseDelay、maxDelay をサポートします。

デフォルトのプロセッサーを置き換えた後で、batch processor を備えたデフォルトの OpenAI エクスポーターを復元したい場合は、 setDefaultOpenAITracingExporter() を呼び出してください。

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

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

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

このデフォルト設定をカスタマイズして、トレースを代替または追加のバックエンドに送信したり、エクスポーターの動作を変更したりするには、2 つの選択肢があります。

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