トレーシング

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

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

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

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

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

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 は、 1 つの「ワークフロー」におけるエンドツーエンドの単一の操作を表します。 Traces は Spans で構成されます。 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: その Span が属するトレースを表します
- parent_id: この Span の親 Span を指します（存在する場合）
- span_data: Span に関する情報です。たとえば、 AgentSpanData には Agent に関する情報、 GenerationSpanData には LLM 生成に関する情報などが含まれます

デフォルトのトレーシング

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

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

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

さらに、カスタムトレースプロセッサーを設定して、トレースを別の送信先に送ることもできます（置き換え先または追加の送信先として）。

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

RealtimeAgent と RealtimeSession をデフォルトの OpenAI Realtime API で使用している場合、 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() でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります

トレースの作成

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

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

スパンの作成

スパンを作成するには、各種 create*Span()（例: createGenerationSpan() 、 createFunctionSpan() など）メソッドを使用できます。一般的には、手動でスパンを作成する必要はありません。カスタムの Span 情報を追跡するために 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 バックエンドに送信されないことを意味します