トレーシング

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

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

ほとんどの環境では、トレースは定期的な間隔で自動的にエクスポートされます。ブラウザや Cloudflare Workers では、この機能はデフォルトで無効です。キューに溜まりすぎた場合はエクスポートされますが、定期的にはエクスポートされません。代わりに、コードのライフサイクルの一部として getGlobalTraceProvider().forceFlush() を使用して手動でトレースをエクスポートしてください。

たとえば Cloudflare Worker では、コードを try/catch/finally ブロックでラップし、waitUntil とあわせて強制フラッシュを使用することで、ワーカーが終了する前にトレースがエクスポートされるようにします。

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: 論理的なワークフローまたはアプリです。例: “Code generation” や “Customer service”
- 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 で名前やその他のプロパティを設定できます。

さらに、custom trace processors を設定して、他の宛先にトレースを送信できます（置き換え、またはセカンダリ宛先）。

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

デフォルトの 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}`);
});

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

トレースの作成

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

現在のトレースは Node.js AsyncLocalStorage または各環境のポリフィルによって追跡されます。つまり、並行実行でも自動的に機能します。

スパンの作成

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

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

機微データ

一部のスパンは機微なデータを含む可能性があります。

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

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

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

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

このデフォルト構成をカスタマイズして、別のバックエンドや追加のバックエンドにトレースを送信したり、エクスポーターの動作を変更したりするには、次の 2 つの方法があります。

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