コンテンツにスキップ

トレーシング

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());
}
},
};
  • トレース は、「ワークフロー」の単一のエンドツーエンド操作を表します。トレースはスパンで構成され、次のプロパティを持ちます。
    • 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による生成に関する情報などが含まれます。

デフォルトでは、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側でトレーシングが自動的に行われます。

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

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

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

現在のトレースは、Node.js の AsyncLocalStorage または各環境のポリフィルを通じて追跡されます。そのため、同時実行にも自動的に対応します。

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 つの方法があります。

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

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

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