トレーシング

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

ノート

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

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

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

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

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

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

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

たとえば、Cloudflare Worker では、コードを try/catch/finally ブロックで囲み、forceFlush() を waitUntil とともに使用して、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());
    }
  },
};

トレースとスパン

• トレースは、「ワークフロー」における単一のエンドツーエンド処理を表します。トレースはスパンで構成され、次のプロパティを持ちます。
  • 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 でラップされます
• トップレベルの Runner 呼び出しごとに TaskSpan でラップされます
• エージェントが実行されるたびに AgentSpan でラップされます
• エージェントループの各反復が TurnSpan でラップされます
• LLM の生成が GenerationSpan でラップされます
• 各関数ツール呼び出しが FunctionSpan でラップされます
• ガードレールが GuardrailSpan でラップされます
• ハンドオフが HandoffSpan でラップされます

デフォルトの階層は TaskSpan → AgentSpan → TurnSpan で、モデルとツールの処理はターンの下にネストされます。タスクスパンは、呼び出しのリクエスト使用量とトークン使用量を集計します。各ターンスパンは、ターン番号、エージェント名、入力、出力、キャッシュ済み入力、キャッシュ書き込みのトークン数を記録します。

タスクスパンとターンスパンはデフォルトで有効です。この追加の階層を省略するには、Runner または個別の実行で tracing: { includeTaskAndTurnSpans: false } を設定します。実行ごとのトレーシングオプションは、Runner レベルの設定を上書きします。

デフォルトでは、トレースには「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または各環境向けのポリフィルを介して追跡されます。そのため、並行処理に自動的に対応します。

スパンの作成

スパンを作成するには、createTaskSpan()、createTurnSpan()、createGenerationSpan()、createFunctionSpan() など、さまざまな create*Span() メソッドを使用できます。withTaskSpan() や withTurnSpan() などの対応するヘルパーは、コールバックを囲むスパンを作成し、そのライフサイクルを管理します。通常、スパンを手動で作成する必要はありません。カスタムスパン情報の追跡には、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