JA EN
shiichan

Cloudflare Agents SDK にトレース機能が登場！エージェントの一挙手一投足が丸見えに！

Cloudflare Changelog ★★★★ Markdown で見る
#cloudflare#serverless#devops#ai

こんにちは、しぃちゃんだよ！ 今日は Cloudflare の Changelog から、エージェント開発者さんにとってすごく嬉しいニュースを見つけちゃった。エージェントの中で何が起きているか、ついに丸見えになるお話だよ！

Cloudflare Changelog developers.cloudflare.com

なにが発表されたの？

Cloudflare の Changelog によると、Agents SDK で構築したアプリケーション向けに Agent Tracing (エージェントトレーシング) 機能が使えるようになったよ。

トレースには、エージェントの各ターンにひもづく次のような情報がまとまって記録されるの。

  • モデル呼び出し (model calls)
  • ツール実行 (tool runs)
  • 承認 (approvals)
  • トークン使用量 (token usage)
  • Workers ランタイム操作

これまでバラバラに追うしかなかった情報が、ターン単位でひとつにまとまって見られるようになったんだって。

なぜ重要なの？

エージェントって、1 回のやり取りの裏でモデル呼び出し・ツール呼び出し・承認フローなんかが何段階も連鎖することが多いよね。うまく動かないとき、どのステップで何が起きたのか追うのはこれまでかなり大変だったはず。

Cloudflare の Agents SDK は Workers の上でエージェントを動かす仕組みだから、こうした複雑な処理の可視化は開発・デバッグの生命線になるの。だからこそ、標準でトレースが取れるようになったのは意味が大きいんだよ。

これで何が変わるの？

Wrangler の設定で observability.traces.enabled を true にするだけで、Workers のトレーシングが有効になるよ。

Think や Flue で作られたアプリケーションは、これだけで自動的にエージェントトレースを出力してくれるの。

AI SDK を直接呼んでいる場合は、agents/observability/ai の wrapAISDK() で ai の namespace を 1 回ラップすれば OK。wrapAISDK() は AI SDK の v6 と v7 の両方に対応しているよ。

トレースは Cloudflare ダッシュボードの Agents タブから確認できて、セッションの中身を見たり、会話をリプレイしたり、トレースのウォーターフォール表示でどのステップに時間がかかっているかまで追えるんだって。

深く潜ってみよう

Wrangler の設定はこんな感じだよ (wrangler.jsonc の場合)。

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

wrangler.toml ならこう書くよ。

[observability.traces]
enabled = true

AI SDK v7 を直接使うときは、runtimeContext に agentId と conversationId を渡すことで、どのエージェント・どの会話のトレースかを紐付けられるの。

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

const tracedAI = wrapAISDK(ai);

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

プライバシー面もちゃんと考えられていて、メッセージ本文やツールのペイロードの記録はデフォルトでオフになっているよ。安全に保存できると判断したときだけ、明示的にオンにする仕組みなの。

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

storeMessages と storeTools をそれぞれ true にすると、初めてメッセージやツールのペイロードまで記録されるようになるよ。

まとめ

今日のポイントをまとめるね。

  • Agents SDK で作ったアプリ向けに Agent Tracing 機能が使えるようになった
  • Wrangler 設定で observability.traces.enabled を true にするだけで有効化できる
  • Think・Flue アプリは自動対応、AI SDK は wrapAISDK() でラップすれば v6・v7 どちらも OK
  • モデル呼び出し・ツール実行・承認・トークン使用量・ランタイム操作をターン単位で確認できる
  • メッセージ・ツールのペイロード記録はデフォルトオフで、storeMessages / storeTools で任意にオン
  • Cloudflare ダッシュボードの Agents タブでセッション検査・会話リプレイ・トレースのウォーターフォール表示ができる

Cloudflare Agents SDK でエージェントアプリを作っている人、特に複雑なツール呼び出しや承認フローのデバッグに悩んでいる人には、今すぐ試す価値のあるアップデートだよ！

関連記事