トレーシング

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

ノート

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

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

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

OpenAI の API を使用し、ゼロデータ保持（ZDR）ポリシーのもとで運用している組織では、トレーシングを利用できません。

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

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

ブラウザーではトレーシングがデフォルトで無効になっているため、このガイダンスは適用されません。

たとえば、Cloudflare Worker では、コードを try/catch/finally ブロックで囲み、waitUntil とともに forceFlush() を使用して、Worker が終了する前にトレースがエクスポートされるようにする必要があります。

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: 論理的なワークフローまたはアプリを表します。たとえば、「コード生成」や「カスタマーサービス」です。
  • 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() 呼び出しを 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}`);
});

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() を使用すると、デフォルトのプロセッサーを独自のトレーシングプロセッサーで 置き換える ことができます。その場合、OpenAI バックエンドへの送信を行う TracingProcessor を含めない限り、トレースは OpenAI バックエンドへ送信されません。

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

• AgentOps
• Respan
• PromptLayer
• Latitude
• Traccia