最近自作コーディングエージェントShaftの動作確認でWorkers AIを使っており、せっかくなのでCloudflareだけで完結するAIエージェントも作ろうと思い立ったのでCloudflare Agentsについて色々調べていたのですが、日本語・英語問わず内部の詳しい資料が全くなかったので、広範囲にわたり調べた内容をまとめることにしました。
今回はちゃんとTool Callingをやっていきます。
APIだけ知りたい人向けのCloudflare Agents Deep Diveはこちら。
まずCloudflare Agentsの開発にはAgent SDKが必要で、このAgent SDKを使いAIエージェントが呼び出すツールを定義したり、ReactでチャットUIを追加したものがChat Agent Starter Kitです。
Cloudflare Agentsのドキュメントと併せて、この2つのリポジトリをCloneして完全に理解すればよさそうですが、ReactやらMCPやらくっついているので、それらを使わない最小限の要素から理解を進めていく必要があります。
前提として、Cloudflare AgentsはCloudflare Workersに依存しているのですが、現在のCloudflare Workersは何ができるのかを理解する必要があります。
ただRuntime APIやBindingを読み進めていっても、ありとあらゆることができることしか分からず困ってしまいます。
2025/09/08現在、cloudflare:workersモジュールのエントリポイントとして以下の3つが用意されていますから、まずはここから始めましょう。
- Cloudflare Workers (
WorkerEntrypoint) - Durable Objects (
DurableObject) - Cloudflare Workflows (
WorkflowEntrypoint)
実際、Agent SDKが発表された数ヶ月後の2025/04/07に、Durable Objectsに無料枠が追加されたり、Cloudflare WorkflowsがGAになったことから、Cloudflare Agentsの利用においても非常に重要であることが分かります。
まずはAgent SDKの以下3つのファイルを見ていきましょう。
これらのファイルはパッケージとしてインポートすることができ、主に以下のクラスを使用することができます。
-
Agent(agentsからインポート) -
AgentClient(agents/clientからインポート) -
AIChatAgent(agents/ai-chat-agentからインポート)
Agent
AgentはAIエージェントを実装するための基本となる抽象クラスで、このクラスを継承して独自のAIエージェントを作成できます。
また、AgentはPartyServerを継承していて、このPartyServerはDurable Objectsを用いたリアルタイムアプリケーション構築のためのコアライブラリです。
Cloudflareがメンテナンスしています。
通常のプロパティとメソッドの他にライフサイクルメソッドというものがあって、必要に応じてサブクラスでオーバーライドしてカスタムロジックを実装できます。
ルーティング関数routeAgentRequest()とヘルパー関数getAgentByName()がありますが、この2つもPartyServerのユーティリティメソッドをAgent用にラップしたものです。
また、@callable(metadata?: CallableMetadata)という謎のデコレータがありますが、これはDurable ObjectsのWebSocket接続を通じて、AgentClientのcall()メソッドと一緒に使います。
他にもタスクスケジューリング、キューイング、Eメール処理、MCPで使える様々なAPIがありますが、長くなるので今回は解説しません。
AgentClient
AgentClientはPartySocketを継承しています。Web標準のWebSocket APIクラスと互換性があり、再接続、バッファリング、耐障害性などの機能を備えています。
ただAgentClientはAgentサーバーへのWebSocket接続を管理するためにあるので、WebSocketを使わずにAgentサーバーへHTTPリクエストを送信したい場合はagentFetch()関数を使います。
ちなみにagents/reactのuseAgent()フックはpartysocket/reactのusePartySocket()フックを使っているので、Agentサーバーとの通信ではWebSocket接続を行っています。
AIChatAgent
AIChatAgentはAgentを継承した、AIチャット機能を持つAIエージェントの基本クラスです。
多くの例ではagents/reactのuseAgent()フックやagents/ai-reactのuseAgentChat()フックと一緒に出てくることが多いですが、状態管理をUIに反映できれば別にReactを使わなくてもいいみたいです。
また、Vercel AI SDKと互換性を持っているため、Vercel AI SDKのAPIとの相性もいいです。
OpenAI SDK
ではVercel AI SDKがなければAgent SDKは使えないのかと思ってしまうのですが、どうやらそんなことはないようです。
Agent SDKのリポジトリにはOpenAI SDKの例があるので、これを確認してみましょう。
AIChatAgentを使わずに継承したAgentクラス内でOpenAI SDKのAgentクラスを呼び出せば良さそうです。
ただクラス名が衝突してしまうので、この例のようにインポート時にCFAgentクラスに名前変更を行う必要がありますし、AIChatAgentで行っているチャット履歴管理は別途実装しなければいけないようです。
Hono
Agent SDKのリポジトリではagentsパッケージだけではなくhono-agentsパッケージも配布しています。
agentsパッケージのrouteAgentRequest()関数をラップしているだけなので、AIエージェントの実装は別途行う必要がありますが、ミドルウェアを追加するだけでより直感的にAIエージェントのルーティングが分かるようになりますし、別のHonoミドルウェアと組み合わせることもできます。
それではChat Agent Starter Kitの以下3つのファイルを見ていきましょう。
これらのファイルは主に以下の処理を行っています。
- Agent SDKの
AIChatAgentを継承したAIエージェントの実装 (server.ts) - Agent SDKの
routeAgentRequest()関数でルーティング (server.ts) -
getWeatherInformation()関数やgetLocalTime()関数といったAIエージェントが呼び出すツールを定義 (tools.ts) -
processToolCalls()関数で確認が必要なツールの処理 (utils.ts)
getWeatherInformation()関数ですが、以下コメントが記載されていることが分かります。
execute()関数が定義されているツールは、AIがそのツールを呼び出した際に自動的に実行されますが、execute()関数が省略されているツールは、人間による確認が必要なツールとして扱われます。
このヒューマン・イン・ザ・ループ (HITL) の確認はprocessToolCalls()関数で行っており、HITL確認が必要なツール呼び出しの状態を永続的に保持できるようになっています。
AIChatAgent(Agent)を継承することで、AIエージェントが休止したり接続が切れたりしても、Durable Objectsで状態を継続できるようにしています。
もちろんチャット履歴、スケジュール、MCPサーバー接続情報などの情報もDurable Objectsに保存されるため、AIエージェントがオフラインになっても失われることはありません。
また、ありとあらゆるところでVercel AI SDKとZodが使われていることが分かりますね。
Vercel AI SDKで@ai-sdk/anthropicや@ai-sdk/googleをインポートすれば簡単にプロバイダやモデルを変更できますし、README.mdに記載されている通りworkers-ai-providerをインポートしてBindingの設定を行えばWorkers AIを使うこともできます。
app.tsxをはじめとした残りのファイルはReactでチャットUIを追加しているだけなので特に解説しません。
- Cloudflare AgentsはCloudflare Workers, Durable Objects, Cloudflare Workflowsを使い倒し、簡単にAIエージェントを開発できるツール
- Agent, AgentClient, AIChatAgentを継承したり、シンプルな関数を使うことで簡単に実装できる
- Durable ObjectsやWebSocketをより便利に扱える、PartyServerとPartySocketについても学ぶことができる
- Cloudflare WorkersやPartyServerでも使えるHonoとの相性もいい
- Vercel AI SDKとOpenAI SDKで学んだ内容がそのまま活かせる
- Workers AIを使えば、Cloudflareアカウントの無料枠で完結する
Views: 0
