トレーシング

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

ノート

トレーシングは、サーバーランタイム (Node.js、Deno、Bun) ではデフォルトで有効です。ブラウザー、および NODE_ENV=test の場合はデフォルトで無効です。

サーバー環境でトレーシングを無効にする方法は 2 つあります:

1. 環境変数 OPENAI_AGENTS_DISABLE_TRACING=1 を設定することで、トレーシングをグローバルに無効化できます
2. new Runner(...) で RunConfig.tracingDisabled を true に設定することで、ランナーのトレーシングを無効化できます

OpenAI の API を使用して Zero Data Retention (ZDR) ポリシーの下で運用している組織では、トレーシングを利用できません。

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

サポートされているサーバーランタイムでは、トレースは一定間隔でエクスポートされます。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}`);
});

1. 2 回の run 呼び出しが withTrace() でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。

トレースの作成

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

現在のトレースは、Node.js の AsyncLocalStorage または各環境に対応するポリフィルを通じて追跡されます。これにより、並行処理でも自動的に動作します。

スパンの作成

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

スパンは自動的に現在のトレースの一部になり、最も近い現在のスパンの下にネストされます。この現在のスパンは、Node.js の AsyncLocalStorage または各環境に対応するポリフィルを通じて追跡されます。

機密データ

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

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

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

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

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

デフォルトのプロセッサーを置き換えた後、バッチプロセッサー付きのデフォルトの OpenAI エクスポーターに戻したい場合は、 setDefaultOpenAITracingExporter() を呼び出してください。

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

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

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

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

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

外部トレーシングプロセッサー一覧

• AgentOps
• Respan
• PromptLayer
• Latitude
• Traccia