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