トレーシング

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

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

対応するサーバーランタイムでは、トレースは一定間隔でエクスポートされます。一部のランタイム（ 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());
    }
  },
};

トレースとスパン

Traces は、 1 つの「ワークフロー」のエンドツーエンドの単一操作を表します。 Traces は Spans で構成されます。 Traces には次のプロパティがあります:
- workflow_name: 論理的なワークフローまたはアプリです。たとえば「 Code generation 」や「 Customer service 」です
- trace_id: トレースの一意な ID です。指定しない場合は自動生成されます。形式は trace_<32_alphanumeric> である必要があります
- group_id: 任意のグループ ID で、同じ会話からの複数トレースを関連付けるために使用します。たとえばチャットスレッド ID を使用できます
- disabled: True の場合、トレースは記録されません
- metadata: トレースの任意メタデータです
Spans は開始時刻と終了時刻を持つ操作を表します。 Spans には次が含まれます:
- started_at と ended_at のタイムスタンプ
- trace_id: その Span が属するトレースを表します
- parent_id: この Span の親 Span （存在する場合）を指します
- span_data: Span に関する情報です。たとえば AgentSpanData には Agent の情報、 GenerationSpanData には LLM 生成の情報が含まれます

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

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

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

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

加えて、custom trace processors を設定して、トレースを他の送信先へ送ることもできます（置き換えまたは二次送信先として）。

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

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

詳細は Voice agents guide を確認してください。

上位レベルのトレース

場合によっては、複数回の 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}`);
});

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(...) で設定してください。 exporter は apiKey 、 endpoint 、 organization 、 project 、 maxRetries 、 baseDelay 、 maxDelay をサポートします。

デフォルトのプロセッサーを置き換えたあとで、バッチプロセッサー付きのデフォルト OpenAI exporter を復元したい場合は、setDefaultOpenAITracingExporter() を呼び出してください。

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

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

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

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

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