コンテンツにスキップ

トレーシング

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());
}
},
};
  • Traces は「ワークフロー」の単一のエンドツーエンドの操作を表します。スパンで構成されます。トレースには次のプロパティがあります:
    • workflow_name: 論理的なワークフローまたはアプリ名。例: “Code generation” や “Customer service”
    • trace_id: トレースの一意 ID。渡さない場合は自動生成。形式は trace_<32_alphanumeric>
    • group_id: 省略可能なグループ ID。同じ会話からの複数のトレースをリンクするためのもの。例: チャットスレッド ID
    • disabled: True の場合、そのトレースは記録されない
    • metadata: トレースの任意のメタデータ
  • Spans は開始時刻と終了時刻を持つ操作を表します。スパンには次が含まれます:
    • started_atended_at のタイムスタンプ
    • 所属するトレースを表す trace_id
    • このスパンの親スパンを指す parent_id(存在する場合)
    • スパンに関する情報である span_data。例えば、AgentSpanData はエージェントに関する情報、GenerationSpanData は LLM の生成に関する情報など

デフォルトで、SDK は以下をトレースします:

  • run() または Runner.run() 全体が Trace でラップされる
  • エージェントが実行されるたびに AgentSpan でラップされる
  • LLM の生成は GenerationSpan でラップされる
  • 関数ツールの呼び出しはそれぞれ FunctionSpan でラップされる
  • ガードレールは GuardrailSpan でラップされる
  • ハンドオフは HandoffSpan でラップされる

デフォルトでは、トレース名は “Agent workflow” です。withTrace を使用する場合はこの名前を設定できますし、RunConfig.workflowName で名前やその他のプロパティを設定することもできます。

さらに、カスタムトレーシングプロセッサー を設定して、他の宛先にトレースを送信できます(置き換えまたは二次宛先として)。

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

Section titled “音声エージェントのトレーシング”

RealtimeAgentRealtimeSession をデフォルトの OpenAI Realtime API と共に使用している場合、RealtimeSessiontracingDisabled: true を設定するか、環境変数 OPENAI_AGENTS_DISABLE_TRACING を使用して無効化しない限り、トレーシングは Realtime API 側で自動的に行われます。

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

複数回の 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}`);
});
  1. run への 2 回の呼び出しが withTrace() でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。

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

現在のトレースは Node.js の AsyncLocalStorage または各環境のポリフィルを通じて追跡されます。これは、自動的に並行実行で機能することを意味します。

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

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

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

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

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

Section titled “カスタムトレーシングプロセッサー”

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

このデフォルトのセットアップをカスタマイズして、別のバックエンドや追加のバックエンドへトレースを送信したり、エクスポーターの動作を変更したりするには、次の 2 つのオプションがあります:

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

外部トレーシングプロセッサー一覧

Section titled “外部トレーシングプロセッサー一覧”