トレーシング

Agents SDK には組み込みのトレーシングがあり、エージェント実行中のイベントを包括的に記録します。これには LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらに発生したカスタムイベントも含まれます。Traces dashboard を使うことで、開発中および本番環境でワークフローのデバッグ、可視化、監視ができます。

エクスポートループのライフサイクル

サポートされているサーバーランタイムでは、トレースは定期的にエクスポートされます。Cloudflare Workers など一部のランタイムでは、トレーシング自体は有効でも自動エクスポートループは利用できません。そのような環境では、ランタイム終了前にキュー済みトレースをエクスポートするため、リクエストライフサイクルの一部として getGlobalTraceProvider().forceFlush() を呼び出してください。

このガイダンスは、ブラウザではデフォルトでトレーシングが無効なため適用されません。

たとえば Cloudflare Worker では、コードを try/catch/finally ブロックで囲み、worker 終了前にトレースがエクスポートされるよう waitUntil と forceFlush() を使う必要があります。

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 は「ワークフロー」の単一のエンドツーエンド操作を表します。複数の Span で構成されます。Traces には次のプロパティがあります:
- workflow_name: 論理的なワークフローまたはアプリです。例: 「 Code generation 」「 Customer service 」
- trace_id: トレースの一意な ID です。指定しない場合は自動生成されます。形式は trace_<32_alphanumeric> である必要があります
- group_id: 任意のグループ ID です。同じ会話の複数トレースを関連付けるために使います。たとえばチャットスレッド ID などです
- disabled: True の場合、トレースは記録されません
- metadata: トレースの任意メタデータです
Spans は開始時刻と終了時刻を持つ操作を表します。Spans には次があります:
- started_at と ended_at のタイムスタンプ
- trace_id: 所属するトレースを表します
- parent_id: この Span の親 Span（存在する場合）を指します
- span_data: Span に関する情報です。例: AgentSpanData はエージェント情報、GenerationSpanData は LLM 生成情報を含みます

デフォルトトレーシング

デフォルトでは、 SDK は次をトレースします。

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

デフォルトでは、トレース名は「 Agent workflow 」です。withTrace を使う場合はこの名前を設定でき、RunConfig.workflowName で名前や他のプロパティも設定できます。

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

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

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

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

上位レベルトレース

場合によっては、複数回の run() 呼び出しを 1 つのトレースに含めたいことがあります。これはコード全体を 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() でラップされるため、それぞれ別々のトレースを作るのではなく、全体トレースの一部になります。

トレースの作成

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

現在のトレースは Node.js AsyncLocalStorage または各環境の polyfill を通じて追跡されます。これは同時実行でも自動的に機能することを意味します。

スパンの作成

create*Span()（例: createGenerationSpan()、createFunctionSpan() など）を使ってスパンを作成できます。通常は手動でスパンを作成する必要はありません。カスタムスパン情報を追跡するために createCustomSpan() 関数も利用できます。

スパンは自動的に現在のトレースに含まれ、最も近い現在のスパンの下にネストされます。これは Node.js AsyncLocalStorage または各環境の polyfill で追跡されます。

機密データ

一部のスパンは機密性の高い可能性があるデータを取得する場合があります。

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

OpenAI トレーシングエクスポーター

サポートされているサーバーランタイムでは、デフォルトのトレーシング設定で既に OpenAI へエクスポートされます。トレースエクスポートで OPENAI_API_KEY とは別の認証情報を使う場合は、setTracingExportApiKey() を使用します。

カスタムの取り込み動作が必要な場合は、OpenAITracingExporter を自分でインスタンス化し、setTraceProcessors(...) または addTraceProcessor(...) で設定してください。エクスポーターは apiKey、endpoint、organization、project、maxRetries、baseDelay、maxDelay をサポートします。

デフォルトプロセッサーを置き換えた後に、バッチプロセッサー付きのデフォルト OpenAI エクスポーターへ戻したい場合は、setDefaultOpenAITracingExporter() を呼び出してください。

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

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

初期化時に、トレース作成を担当するグローバルな TraceProvider を作成し、getGlobalTraceProvider() からアクセスできます
TraceProvider は BatchTraceProcessor で設定され、トレース/スパンをバッチで OpenAITracingExporter に送信します。これによりスパンとトレースがバッチで OpenAI バックエンドへエクスポートされます

このデフォルト設定をカスタマイズし、別のまたは追加のバックエンドへトレースを送信したり、エクスポーター動作を変更したりするには、2 つの方法があります。

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