トレーシング

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());
    }
  },
};

トレースとスパン

Traces は「ワークフロー」の単一のエンドツーエンドの操作を表します。複数の Span で構成されます。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_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}`);
});

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

トレースの作成

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

現在のトレースは Node.js の AsyncLocalStorage または該当する環境のポリフィルを通じて追跡されます。これは自動的に並行性に対応することを意味します。

スパンの作成

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

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

機微なデータ

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

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

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

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

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

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

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