トレーシング

エージェントトレーシングは、各ターンでエージェントが何をしたかを把握するのに役立ちます。モデル呼び出し、ツール実行、承認リクエストを含みます。想定外の動作の調査、遅い操作の特定、トークン使用量の確認にトレースを使います。

エージェントのアクティビティは、fetch 呼び出し、KV 読み取り、D1 クエリなどのランタイムイベントと並んで、Workers トレース に表示されます。

Wrangler 設定でトレーシングを有効にします。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "observability": {
    "traces": {
      "enabled": true
    }
  }
}

[observability.traces]
enabled = true

Cloudflare ダッシュボードの Agents タブ ↗ を開き、トレースされたエージェントとサブエージェントを確認します。概要には、各エージェントのモデル、セッション数、実行回数、トークン使用量の合計が表示されます。

セッションは、1 回以上のターンからなる会話です。ターンは、エージェントへの 1 回のリクエストとその応答です。

エージェントを選択すると、そのトレースを確認できます。各トレースには、所要時間、トークン内訳、ステータスが含まれます。

エージェントの動きを追う方法は 2 つあります。Session replay と Trace です。

Session replay は、ターンをまたいだ記録済みの会話を表示します。メッセージ、推論、ツール呼び出し、サブエージェントのアクティビティを含みます。表示内容は ペイロード記録の設定 に依存します。

Trace は、1 ターン中に行われた操作のウォーターフォールです。各操作の開始時点、所要時間、どの操作から呼ばれたかを示します。

各ターンは、時間計測された操作ごとのスパンからなるトレースを生成します。

invoke_agent {agent class}
├── chat {model}
└── execute_tool {tool}
    └── tool_approval {tool}

invoke_agent スパンがターン全体を覆います。モデル呼び出し、ツール実行、承認は入れ子のスパンとして現れます。サブエージェントの作業は、それを呼び出した操作の下に現れます。

エージェントスパンは、ダッシュボードに表示する作業を識別するために、次の 3 つのフィールドを使います。

• Agent name は、論理的なエージェント実装を識別します。booking-agent のような共有名を使います。
• Agent ID は、安定したエージェントインスタンスまたはリソースを識別します。例: booking-agent-production。
• Conversation ID は、現在の会話またはセッションを識別します。

エージェント名を、リクエスト、会話、ユーザー識別子から導出しないでください。ダッシュボード上のエージェント名が増えすぎます。

メッセージとツールのペイロードには、個人を特定できる情報が含まれることがあります。保存してよいペイロードだけを記録してください。統合ごとにペイロード記録の制御は異なるため、該当する フレームワークのセットアップ で設定します。

Think と wrapAISDK() は、storeMessages で chat スパンの入出力メッセージを記録します。storeTools で execute_tool スパンの引数と結果を記録します。

トレーシングとペイロード制御は、統合に依存します。Think と Flue はターンを自動で計装します。直接の AI SDK 呼び出しとカスタムハーネスには、追加のセットアップが必要です。

Think はエージェントを自動で計装し、標準のスパン構造 を発行します。追加のトレーシング設定は不要です。

Think は、デフォルトではメッセージやツールのペイロードを保存しません。記録するには、エージェントクラスのプロパティをオーバーライドします。

import { Think } from "@cloudflare/think";

export class MyAgent extends Think {
	storeMessages = true;
	storeTools = true;
}

import { Think } from "@cloudflare/think";

export class MyAgent extends Think<Env> {
	override storeMessages = true;
	override storeTools = true;
}

Flue v2+ ↗ も、エージェントを自動で計装し、標準のスパン構造 を発行します。追加のトレーシング設定は不要です。

Flue は、デフォルトでメッセージ、システム指示、ツール定義、引数、結果を保存します。記録を止めるには、content を false にします。

import { instrument } from "@flue/runtime";
import { createCloudflareTracing } from "@flue/runtime/cloudflare";

instrument(createCloudflareTracing({ content: false }));

import { instrument } from "@flue/runtime";
import { createCloudflareTracing } from "@flue/runtime/cloudflare";

instrument(createCloudflareTracing({ content: false }));

直接の AI SDK ↗ 呼び出しでは、名前空間を一度ラップします。

import * as ai from "ai";
import { wrapAISDK } from "agents/observability/ai";

const tracedAI = wrapAISDK(ai);

import * as ai from "ai";
import { wrapAISDK } from "agents/observability/ai";

const tracedAI = wrapAISDK(ai);

wrapAISDK() は AI SDK v6 と v7 をサポートします。generateText、streamText、generateObject、streamObject を計装し、モデルとツールの作業が始まる前に親の invoke_agent を作ります。

Think と違い、直接の AI SDK 呼び出しには、ダッシュボード識別を推測できる Agent インスタンスがありません。呼び出しごとに エージェント識別フィールド を渡してください。

保存してよいコンテキストだけを含めてください。認証情報、トークン、ユーザー入力、その他の秘密は含めないでください。

識別情報の受け渡しには、AI SDK v7 ネイティブのテレメトリフィールドを使います。テナントやルートなど、追加のスカラーコンテキストを含めると、トレースを検索しやすくなります。

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	runtimeContext: {
		agentId: "booking-agent-production",
		conversationId: "conversation-123",
		tenantId: "tenant-42",
	},
	telemetry: {
		functionId: "booking-agent",
		includeRuntimeContext: {
			agentId: true,
			conversationId: true,
			tenantId: true,
		},
	},
});

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	runtimeContext: {
		agentId: "booking-agent-production",
		conversationId: "conversation-123",
		tenantId: "tenant-42",
	},
	telemetry: {
		functionId: "booking-agent",
		includeRuntimeContext: {
			agentId: true,
			conversationId: true,
			tenantId: true,
		},
	},
});

これは functionId、agentId、conversationId を gen_ai.agent.name、gen_ai.agent.id、gen_ai.conversation.id へ対応付けます。その他のスカラー値は cloudflare.agents.runtime_context.* 名前空間を使います。

AI SDK v6 は、同じ識別情報と追加のスパンデータに experimental_telemetry.metadata を使います。

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	experimental_telemetry: {
		functionId: "booking-agent",
		metadata: {
			agentId: "booking-agent-production",
			conversationId: "conversation-123",
			tenantId: "tenant-42",
		},
	},
});

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	experimental_telemetry: {
		functionId: "booking-agent",
		metadata: {
			agentId: "booking-agent-production",
			conversationId: "conversation-123",
			tenantId: "tenant-42",
		},
	},
});

追加のスカラーメタデータは cloudflare.agents.metadata.* 名前空間を使います。

wrapAISDK() は、デフォルトではメッセージやツールのペイロードを保存しません。AI SDK v6 または v7 で記録するには、名前空間をラップするときに保存オプションを渡します。

import * as ai from "ai";
import { wrapAISDK } from "agents/observability/ai";

const tracedAI = wrapAISDK(ai, {
	storeMessages: true,
	storeTools: true,
});

import * as ai from "ai";
import { wrapAISDK } from "agents/observability/ai";

const tracedAI = wrapAISDK(ai, {
	storeMessages: true,
	storeTools: true,
});

現在サポートしているフレームワークを使わないエージェントでは、Workers のカスタムスパン API で計装します。各ターンに invoke_agent スパンを作り、モデル呼び出しに chat スパン、ツール実行に execute_tool スパン、承認に tool_approval スパンを置きます。

スパン名、属性、実装例は OpenTelemetry GenAI の参照実装 ↗ を参照してください。これらの例を、Workers のカスタムスパン API に合わせてください。

Agents ダッシュボードがテレメトリをエージェントと会話に関連付けられるよう、invoke_agent スパンと chat スパンの両方に、次の属性を追加します。

カスタムスパンでは、ペイロード属性を手動で追加します。モデルスパンには gen_ai.input.messages、gen_ai.output.messages、gen_ai.system_instructions を使います。ツールスパンには gen_ai.tool.call.arguments と gen_ai.tool.call.result を使います。カスタムスパン API はスカラー属性値を受け取るため、構造化ペイロードは JSON.stringify() でシリアライズします。これらの値は、呼び出しがサンプリングされたときに記録されます。保存してよいペイロードだけを追加してください。

スパン属性は OpenTelemetry Generative AI セマンティック規約 ↗ に従うため、OpenTelemetry データを読むツールなら消費できます。外部送信先へトレースを送るには、Workers Observability で OpenTelemetry Protocol（OTLP）エンドポイント を設定します。

エージェントトレースは Workers トレーシング を使い、Workers Observability の料金に従います。

Agents ビューは、エージェントの操作を表示します。Worker トレース全体には、SDK 内部や他の Worker レベルの操作からの追加スパンが含まれることがあります。トレース全体を調べるには、Observability で表示 を選択します。

Agents ビューに出ないスパンも含め、各スパンは 1 件の可観測性イベントとして数えます。ベータ中のトレーシングは無料です。2026 年 10 月 1 日以降、トレーシングは既存の Workers Observability 料金に含まれます。

• エージェントトレースは、デバッグと可観測性向けです。会話の完全または無損失の記録ではありません。
• ペイロードデータはスパンサイズ制限の対象です。長いメッセージ、推論、ツール引数、結果は切り詰められることがあります。これらの制限は変わる可能性があります。
• Session replay は画像を表示しません。