トレーシング
Agents SDK には組み込みのトレーシングがあり、エージェントの実行中に発生するイベントを包括的に記録します。LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにカスタムイベントまでを収集します。Traces ダッシュボードを使うと、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。
エクスポートループのライフサイクル
Section titled “エクスポートループのライフサイクル”多くの環境では、トレースは一定間隔で自動的にエクスポートされます。ブラウザや 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()); } },};トレースとスパン
Section titled “トレースとスパン”- Traces は「ワークフロー」の単一のエンドツーエンドな操作を表します。Spans で構成されます。Traces には次のプロパティがあります:
workflow_name: 論理的なワークフローまたはアプリ。例: “Code generation” や “Customer service”trace_id: トレースの一意 ID。未指定の場合は自動生成。形式はtrace_<32_alphanumeric>group_id: 同一会話の複数トレースを関連付けるための任意のグループ ID。例: チャットスレッドの IDdisabled: True の場合、トレースは記録されないmetadata: トレースの任意メタデータ
- Spans は開始時刻と終了時刻を持つ操作を表します。Spans には次があります:
started_atとended_atのタイムスタンプ- 所属するトレースを表す
trace_id - この Span の親を指す
parent_id(ある場合) span_data: Span に関する情報。例:AgentSpanDataはエージェント情報、GenerationSpanDataは LLM 生成情報など
デフォルトのトレーシング
Section titled “デフォルトのトレーシング”デフォルトで SDK は次をトレースします:
run()またはRunner.run()全体をTraceでラップ- エージェント実行ごとに
AgentSpanでラップ - LLM 生成は
GenerationSpanでラップ - 関数ツール呼び出しはそれぞれ
FunctionSpanでラップ - ガードレールは
GuardrailSpanでラップ - ハンドオフは
HandoffSpanでラップ
デフォルトでは、トレース名は “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 “スパンの作成”create*Span()(例: createGenerationSpan()、createFunctionSpan() など)でスパンを作成できます。一般に、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するために createCustomSpan() 関数が利用できます。
スパンは自動的に現在のトレースの一部となり、Node.js の AsyncLocalStorage または各環境のポリフィルによって追跡される最も近い現在のスパンの下にネストされます。
一部のスパンは機微なデータを含む可能性があります。
createGenerationSpan() は LLM 生成の入出力を保存し、createFunctionSpan() は関数呼び出しの入出力を保存します。これらには機微なデータが含まれる可能性があるため、RunConfig.traceIncludeSensitiveData によってそのデータの収集を無効化できます。
カスタムトレーシングプロセッサー
Section titled “カスタムトレーシングプロセッサー”トレーシングの高レベルなアーキテクチャは次のとおりです:
- 初期化時にグローバルな
TraceProviderを作成します。これはトレースの作成を担い、getGlobalTraceProvider()からアクセスできます TraceProviderにはBatchTraceProcessorを設定し、トレース/スパンをバッチでOpenAITracingExporterに送信します。エクスポーターはスパンとトレースをバッチで OpenAI のバックエンドにエクスポートします
このデフォルト構成をカスタマイズして、別のバックエンドや追加のバックエンドへ送信したり、エクスポーターの動作を変更するには、次の 2 つの方法があります:
addTraceProcessor()は、トレースとスパンが準備でき次第受け取る追加のトレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理を行えますsetTraceProcessors()は、デフォルトのプロセッサーを独自のトレースプロセッサーに置き換えられます。これを行うと、OpenAI のバックエンドにトレースは送信されません。送信したい場合はその役割を持つTracingProcessorを含める必要があります