JA EN
shiichan

Agents SDK、MCP 接続の HTTP オーバーヘッドとはお別れ！

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

こんにちは、しぃちゃんだよ！今日は Cloudflare の Agents SDK に気になるアップデートを見つけたの。Agent と McpAgent を同じ Worker の中に置いて、HTTP を挟まずに直接つなげられるようになったんだって。さっそく中身を見ていこう。

Cloudflare Changelog developers.cloudflare.com

なにが発表されたの？

Cloudflare Changelog によると、Agents SDK v0.6.0 では Agent から McpAgent への接続を RPC 経由でできるようになった。同じ Worker の中に定義した Agent と McpAgent を、HTTP URL ではなく Durable Object のバインディングで直結できる仕組み。ネットワークのラウンドトリップやシリアライズのオーバーヘッドが発生せず、Cloudflare のランタイム内だけで完結する。

あわせて、シンプルな MCP 接続では OAuth を必須にしないオプトイン方式に変更されたほか、generateTypes() や getAITools() が使うスキーマ変換の耐障害性が強化され、@cloudflare/ai-chat のバグ修正もまとめて入ったよ。

今までどうだったの？

これまでは、たとえ Agent と McpAgent が同じ Worker 内に定義されていても、つなぐ手段は HTTP URL 経由の接続しか用意されていなかった。ネットワークを挟むぶんレイテンシやシリアライズのコストがかかっていたし、addMcpServer() はすべての接続に対して毎回 OAuth プロバイダを作っていたから、認証が要らないシンプルな MCP サーバーにつなぐだけでも余計なセットアップを背負うことになっていたみたい。

これで何が変わるの？

Durable Object のネームスペースを addMcpServer に直接渡すだけで、同じ Worker 内の Agent と McpAgent を RPC でつなげるようになった。

import { Agent } from "agents";

export class MyAgent extends Agent {
  async onStart() {
    // DO バインディング経由で接続。HTTPもネットワークオーバーヘッドも無し
    await this.addMcpServer("counter", env.MY_MCP);

    // props でユーザーごとのコンテキストも渡せる
    await this.addMcpServer("counter", env.MY_MCP, {
      props: { userId: "user-123", role: "admin" },
    });
  }
}

addMcpServer の第 2 引数は string | DurableObjectNamespace を受け取る TypeScript オーバーロード付きになっていて、HTTP と RPC のパスを型レベルで混ぜられない設計になっているところも安心。

OAuth まわりも身軽になった。認証が要らないサーバーにつなぐときは、callbackHost も OAuth の設定も書かずにそのまま呼ぶだけでいい。サーバー側が 401 を返してきたときだけ「callbackHost を渡して OAuth フローを有効にして」という明確なエラーが出る仕組みに変わったから、要らない設定を先回りして書かずに済むようになったの。

深く潜ってみよう

RPC 接続には、こんな特徴がある。

  • Hibernation 対応: Durable Object がハイバネートしても RPC 接続は自動的に復元される。バインディング名と props はストレージに保存され、起き上がるときに復元される。HTTP 経由の MCP 接続と同じ挙動
  • 重複排除: 同じサーバー名で addMcpServer を呼ぶと、新しい接続を作らずに既存の接続を返す。接続 ID はハイバネーション復元後も安定して保たれる
  • 実装のスリム化: RPC トランスポート内部は 609 行から 245 行に書き直され、RPCServerTransport は自前のチェックの代わりに MCP SDK の JSONRPCMessageSchema でバリデーションするようになった

スキーマ変換まわりも、本番運用で実際に落ちていたケースをつぶす方向で手が入っている。

  • 再帰的・深いネストのスキーマでスタックオーバーフローしないよう、深さと循環参照のガードを追加
  • #/definitions/... や #/$defs/... といった内部 JSON Pointer の $ref 解決に対応
  • JSON Schema 2020-12 の prefixItems と draft-07 の配列 items、両方の書き方でタプルをサポート
  • OpenAPI 3.0 の nullable: true を全スキーマ分岐で解釈できるように
  • 1 つのツールのスキーマが壊れていても、generateTypes() や getAITools() のパイプライン全体を落とさない単位でエラーを隔離
  • inputSchema が無いときは例外を投げず { type: "object" } にフォールバック

@cloudflare/ai-chat の修正もボリュームがある。ツールの承認を拒否(approved: false)したときに output-denied へきちんと遷移して Anthropic プロバイダとの互換性が直ったり、ストリーミング中に abort シグナルが来たときにリーダーループを確実にキャンセルして done を送るようになったり、persistMessages() がメッセージを内容と順序で突き合わせて重複行を防ぐようになったりと、地味だけど効く修正が並んでいる。加えて createToolsFromClientSchemas や clientTools、AITool、extractClientToolSchemas、useAgentChat の tools オプションが非推奨から復活していて、実行時に動的にツールを定義したいケースでも使えるようになったの。

アップデートは次のコマンド 1 行で完了。

npm i agents@latest @cloudflare/ai-chat@latest

まとめ

今回の Agents SDK v0.6.0 で押さえておきたいポイントはこちら。

  • Agent と McpAgent を同じ Worker 内で RPC 接続でき、HTTP のオーバーヘッド無しでつながる
  • 認証不要な MCP サーバーには OAuth 設定を書かなくてよくなり、401 のときだけ親切なエラーで教えてくれる
  • スキーマ変換に深さ・循環参照ガードや $ref 解決が入り、本番での予期しないクラッシュに強くなった
  • @cloudflare/ai-chat はツール拒否・abort・重複メッセージなど細かい不具合がまとめて修正された

Worker の中で複数の Agent や MCP サーバーを組み合わせて動かしている人には、まさに刺さるアップデートだと思う！

関連記事