トレーシング
Agents SDKにはトレーシングが組み込まれており、エージェントの実行中に発生するイベントを包括的に記録します。これには、LLMによる生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントも含まれます。トレースダッシュボードを使うと、開発中および本番環境でワークフローのデバッグ、可視化、監視ができます。
エクスポートループのライフサイクル
Section titled “エクスポートループのライフサイクル”対応するサーバーランタイムでは、トレースは一定間隔でエクスポートされます。Cloudflare Workers などの一部のランタイムでは、トレーシング自体は有効でも、自動エクスポートループは利用できません。これらの環境では、ランタイムが終了する前にキュー内のトレースをエクスポートするため、リクエストのライフサイクルの一部として getGlobalTraceProvider().forceFlush() を呼び出す必要があります。
ブラウザーではトレーシングがデフォルトで無効なため、このガイダンスは適用されません。
たとえば、Cloudflare Worker では、コードを try/catch/finally ブロックで囲み、forceFlush() と 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('Internal Server Error', { status: 500 }); } finally { // make sure to flush any remaining traces before exiting ctx.waitUntil(getGlobalTraceProvider().forceFlush()); } },};トレースとスパン
Section titled “トレースとスパン”- トレース は、「ワークフロー」の単一のエンドツーエンド操作を表します。トレースはスパンで構成され、次のプロパティを持ちます。
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による生成に関する情報などが含まれます。
デフォルトのトレーシング
Section titled “デフォルトのトレーシング”デフォルトでは、SDK は次の項目をトレースします。
run()またはRunner.run()全体がTraceでラップされます。- トップレベルのランナー呼び出しは、それぞれ
TaskSpanでラップされます。 - エージェントは、実行されるたびに
AgentSpanでラップされます。 - エージェントループの各反復は
TurnSpanでラップされます。 - LLMによる生成は
GenerationSpanでラップされます。 - 関数ツールの呼び出しは、それぞれ
FunctionSpanでラップされます。 - ガードレールは
GuardrailSpanでラップされます。 - ハンドオフは
HandoffSpanでラップされます。
デフォルトの階層は TaskSpan → AgentSpan → TurnSpan で、モデルとツールの処理はターンの下にネストされます。タスクスパンは、呼び出しのリクエストとトークンの使用量を集計します。各ターンスパンは、ターン番号、エージェント名、および入力、出力、キャッシュ済み入力、キャッシュ書き込みのトークン数を記録します。
タスクスパンとターンスパンはデフォルトで有効です。この追加の階層を省略するには、Runner または個々の実行で tracing: { includeTaskAndTurnSpans: false } を設定します。実行ごとのトレーシングオプションは、ランナーレベルの設定より優先されます。
デフォルトでは、トレースには「Agent workflow」という名前が付けられます。withTrace を使う場合はこの名前を設定できます。また、RunConfig.workflowName を使って、名前やその他のプロパティを設定することもできます。
さらに、カスタムトレーシングプロセッサーを設定して、トレースを別の送信先へ送ることもできます(既存の送信先の代わりに、または追加の送信先として)。
音声エージェントのトレーシング
Section titled “音声エージェントのトレーシング”RealtimeAgent と RealtimeSession をデフォルトのOpenAI Realtime APIとともに使う場合、RealtimeSession で tracingDisabled: true を設定するか、環境変数 OPENAI_AGENTS_DISABLE_TRACING を使って無効にしない限り、Realtime API側でトレーシングが自動的に行われます。
詳細については、音声エージェントの概要を参照してください。
上位レベルのトレース
Section titled “上位レベルのトレース”複数の 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}`);});- 2 つの
run呼び出しがwithTrace()で囲まれているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。
トレースの作成
Section titled “トレースの作成”withTrace() 関数を使ってトレースを作成できます。また、getGlobalTraceProvider().createTrace() を使って新しいトレースを手動で作成し、withTrace() に渡すこともできます。
現在のトレースは、Node.js の AsyncLocalStorage または各環境のポリフィルを通じて追跡されます。そのため、同時実行にも自動的に対応します。
スパンの作成
Section titled “スパンの作成”createTaskSpan()、createTurnSpan()、createGenerationSpan()、createFunctionSpan() など、さまざまな create*Span() メソッドを使ってスパンを作成できます。対応する withTaskSpan() や withTurnSpan() などのヘルパーは、スパンを作成し、コールバックを囲むスパンのライフサイクルを管理します。通常、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するために、createCustomSpan() 関数が用意されています。
スパンは自動的に現在のトレースの一部となり、現在の最も近いスパンの下にネストされます。現在のスパンは、Node.js の AsyncLocalStorage または各環境のポリフィルを通じて追跡されます。
一部のスパンでは、機密性の高いデータが記録される可能性があります。
createGenerationSpan() はLLMによる生成の入力と出力を保存し、createFunctionSpan() は関数呼び出しの入力と出力を保存します。これらには機密データが含まれる可能性があるため、RunConfig.traceIncludeSensitiveData を使って、そのデータの記録を無効にできます。
OpenAIトレーシングエクスポーター
Section titled “OpenAIトレーシングエクスポーター”対応するサーバーランタイムでは、デフォルトのトレーシング設定ですでにOpenAIへのエクスポートが行われます。トレースのエクスポートに OPENAI_API_KEY とは異なる認証情報を使う場合は、setTracingExportApiKey() を使用してください。
カスタムの取り込み動作が必要な場合は、OpenAITracingExporter を自分でインスタンス化し、setTraceProcessors(...) または addTraceProcessor(...) で設定してください。このエクスポーターは、apiKey、endpoint、organization、project、maxRetries、baseDelay、maxDelay をサポートしています。
デフォルトのプロセッサーを置き換えた後、バッチプロセッサー付きのデフォルトのOpenAIエクスポーターに戻したい場合は、setDefaultOpenAITracingExporter() を呼び出してください。
カスタムトレーシングプロセッサー
Section titled “カスタムトレーシングプロセッサー”トレーシングの大まかなアーキテクチャは次のとおりです。
- 初期化時に、グローバルな
TraceProviderが作成されます。これはトレースの作成を担当し、getGlobalTraceProvider()を通じてアクセスできます。 TraceProviderには、トレースとスパンをバッチでOpenAITracingExporterに送信するBatchTraceProcessorが設定されます。このエクスポーターは、スパンとトレースをOpenAIのバックエンドにバッチでエクスポートします。
このデフォルト設定をカスタマイズして、別のバックエンドや追加のバックエンドにトレースを送信したり、エクスポーターの動作を変更したりするには、次の 2 つの方法があります。
addTraceProcessor()を使うと、トレースとスパンの準備ができ次第それらを受け取るトレースプロセッサーを 追加 できます。これにより、OpenAIのバックエンドへのトレース送信に加えて、独自の処理を行えます。setTraceProcessors()を使うと、デフォルトのプロセッサーを独自のトレースプロセッサーに 置き換える ことができます。この場合、OpenAIのバックエンドに送信するTracingProcessorを含めない限り、トレースはOpenAIのバックエンドに送信されません。