トレーシング

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

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

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

たとえば Cloudflare Worker では、コード全体を try/catch/finally ブロックでラップし、waitUntil と組み合わせて force flush を呼び出すことで、ワーカーが終了する前にトレースを確実にエクスポートできます。

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

Trace と Span

Trace は 1 回のワークフロー全体 (end-to-end) の操作を表し、複数の Span で構成されます。Trace には次のプロパティがあります:
- workflow_name: 論理的なワークフローまたはアプリ名例: “Code generation” や “Customer service”
- trace_id: Trace の一意 ID。指定しない場合は自動生成され、形式は trace_<32_alphanumeric>
- group_id: 同じ会話からの複数トレースを関連付けるオプションのグループ ID。たとえばチャットスレッド ID など
- disabled: true の場合、この Trace は記録されない
- metadata: Trace 用の任意メタデータ
Span は開始時刻と終了時刻を持つ操作を表します。Span には次のプロパティがあります:
- started_at と ended_at のタイムスタンプ
- 所属する Trace を示す 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 で名前や他のプロパティを設定できます。

さらに、カスタムトレースプロセッサーを設定して、トレースを別の送信先に転送（置き換えや追加送信）することもできます。

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

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

詳細は音声エージェントの概要を参照してください。

上位レベルのトレース

複数回の run() 呼び出しを 1 つの Trace にまとめたい場合は、コード全体を 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() でラップされているため、それぞれの実行は個別の Trace を作成せず、全体 Trace の一部になります。

Trace の作成

withTrace() 関数で Trace を作成できます。あるいは getGlobalTraceProvider().createTrace() で新しい Trace を手動作成し、それを withTrace() に渡す方法もあります。

現在の Trace は Node.js AsyncLocalStorage（または各環境のポリフィル）で管理されるため、自動的に並行処理に対応します。

Span の作成

createGenerationSpan() や createFunctionSpan() などの create*Span() メソッドで Span を作成できます。通常は手動で Span を作成する必要はありません。カスタム情報を追跡したい場合は createCustomSpan() を使用できます。

Span は自動的に現在の Trace に属し、最も近い現在の Span の子としてネストされます。この情報も Node.js AsyncLocalStorage で管理されます。

機密データ

一部の Span では機密データが記録される可能性があります。

createGenerationSpan() は LLM 生成の入力／出力を、createFunctionSpan() は関数呼び出しの入力／出力を保存します。機密データを含む可能性があるため、RunConfig.traceIncludeSensitiveData で記録を無効化できます。

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

トレーシングの高レベル構成は以下のとおりです:

初期化時にグローバル TraceProvider を作成し、getGlobalTraceProvider() から取得できます。
TraceProvider には BatchTraceProcessor を設定し、Trace / Span をバッチで OpenAITracingExporter に送信して OpenAI バックエンドへエクスポートします。

デフォルト設定を変更し、別のバックエンドへ送信したりエクスポーターの挙動を変更したりするには、次の 2 つの方法があります:

addTraceProcessor()
追加のトレースプロセッサーを登録し、Trace / Span が準備でき次第受け取れるようにします。これにより、OpenAI バックエンドへの送信に加えて独自処理を実行できます。
setTraceProcessors()
既定のプロセッサーを置き換えて独自のトレースプロセッサーのみを使用します。OpenAI バックエンドへ送信したい場合は、その機能を持つ TracingProcessor を含める必要があります。