cloudflare/agents

Cloudflare Agents – 状態保持型、サーバーサイドAI/ツールエージェント

何であるか – Cloudflare Workers上でDurable Objectsを書くことができるTypeScript/JavaScript SDK。各オブジェクトを独立した長期間生存する「エージェント」として扱える。エージェントには独自の永続的ストレージがあり、スケジュールされたジョブを実行でき、WebSocket接続を維持し、AIモデルを呼び出し、MCP（マルチチャネルプロトコル）サーバーまたはクライアントとして動作し、@callable()デコレータでタイプセーフなRPCメソッドを公開できる。ランタイムはアイドル状態のエージェントを自動的にスリープさせ、必要時に起動するため、ユーザー単位やセッション単位のエージェントを数百万規模で展開しても、アイドルコストはほぼゼロとなる。

コアコンセプト

コンセプト	何が得られるか
永続的状態	状態はCloudflare Durable Objectに保存され、再起動後も保持される。変更はすべて接続されたクライアントに自動的に同期される。
呼び出し可能なメソッド	`@callable()`でクラスメソッドをデコレート – ブラウザや他のWorkersから呼び出せるタイプセーフなRPCエンドポイントになる。
サブエージェント	エージェントはファセットとネストされたルーティングを通じて他のエージェント（親/子）を組み合わせられ、階層的なワークロードを実現できる。
スケジューリング	1回限り、繰り返し、またはcron形式のタスクをエージェント内にスケジュール可能。
WebSockets	ライフサイクルフック付きのリアルタイム双方向チャネルが組み込み済み。
AIチャット & ツール	永続メッセージを保持し、再開可能なストリーミングをサポートするチャットレイヤー（`@cloudflare/ai-chat`）が内蔵。子エージェントを「ツール」として実行可能。
MCP / WebMCP	エージェントはマルチチャネルプロトコル（HTTP、SSE、RPCなど）を公開または利用でき、ブラウザとツールを橋渡しできる。
ワークフロー	パースンインザループの複数ステッププロセスで、一時停止/再開、承認ステップを含む。
メール & 音声	Cloudflare Email Serviceおよび音声パイプライン（STT/TTS、VAD、SFU）と直接統合。
コードモード	LLMがツールを呼び出すTypeScriptコードを生成し、サンドボックス化されたWorker（`@cloudflare/shell`）で実行される。
支払い（x402）	1回の呼び出しごとに課金されるAPIをx402プロトコルで請求可能。
観測性	自動的にトレーシング、メトリクス、構造化ログが発行される。
SQL	エージェントはDurable Object内で直接SQLiteクエリを実行できる。
フロントエンドフック	Reactフック（`useAgent`、`useAgentChat`、`useVoiceAgent`）とVanilla JSクライアント（`AgentClient`）により、統合が容易。

モノレポ内のパッケージ

パッケージ	役割
`agents`	コアSDK – エージェント、ルーティング、スケジューリング、MCP、ワークフロー、音声、ブラウザエージェントなど
`@cloudflare/ai-chat`	永続メッセージとツール実行を備えた高レベルなチャット抽象化
`@cloudflare/think`	意思決定ループとワークスペースユーティリティを追加するオピニオン付きチャットエージェントベース
`@cloudflare/codemode`	LLM出力を実行可能なTypeScriptに変換し、ツールを呼び出す
`@cloudflare/shell`	サンドボックス化されたJS実行と仮想ファイルシステムによる安全なコードモード実行
`@cloudflare/voice`	音声APIの互換性ラッパー（`agents/voice`のエクスポートに移行中で非推奨）
`@cloudflare/worker-bundler`	ランタイムでWorkersをバンドルする（Worker-Loaderバインディングと併用）
`hono-agents`	Honoウェブフレームワークアプリにエージェントを追加するミドルウェア

一般的なユースケース

ユーザー単位のアシスタント – ユーザーごとに1つのエージェントが会話履歴、設定、スケジュールされたリマインダーを保存。
リアルタイムマルチプレイヤールーム – 各ゲームルームがエージェントとして、WebSocketで全プレイヤーに状態を同期。
ツール呼び出しAIアシスタント – LLMが子エージェント（例：カレンダーエージェント、検索エージェント）を呼び出し、結果をストリーミングでユーザーに返信。
ワークフロー自動化 – 複雑な複数ステッププロセス（例：チケットトライアージ → 人間承認 → 実行）を永続的なワークフローとしてモデル化。
音声ボット – STT/TTSサービスとエージェントを組み合わせ、会話状態を維持し、他のツールを呼び出せる。
1回呼び出しごとの課金API – 関数をx402課金エンドポイントとして公開。エージェントが課金とスロットリングを処理。

セットアップ手順（READMEから）

スタータープロジェクトを作成

npm create cloudflare@latest -- --template cloudflare/agents-starter

既存のWorkerにSDKを追加
```
npm install agents
```
エージェントを書く – Agentを継承し、@callable()でメソッドをマーク（READMEのカウンタ例を参照）。
wrangler.jsoncでDurable Objectsを設定（バインディング名、クラス名、SQLiteマイグレーションタグ）。
Cloudflare Wranglerでデプロイ – 通常のWorkerと同様に。
ブラウザから利用 – ReactフックuseAgent（またはVanilla AgentClient）を使用してメソッドを呼び出し、リアルタイムの状態更新を受信。

ドキュメントと学習リソース

完全なドキュメント – https://developers.cloudflare.com/agents/（導入ガイド、APIリファレンス、チュートリアル）。
例 – examples/に30以上ある自己完結型デモ（プレイグラウンド、チャットアシスタント、MCPサーバー/クライアント、コードモード、音声パイプライン、ワークフローなど）。
設計ドキュメント – design/にはアーキテクチャ意思決定記録とパターンガイド（Anthropicパターン、人間が関与するプロセスなど）。
OpenAI SDKの例 – openai-sdk/では、Cloudflareエージェントと組み合わせたOpenAI Agents JavaScript SDKの使い方を示す。

開発ワークフロー（貢献者向け）

Node 24+、pnpmワークスペース、Nxによるタスクオーケストレーション。
ビルド：pnpm run build（Nxが依存関係順にパッケージをビルドし、結果をキャッシュ）。
ライントypeチェック：pnpm run check。
テスト：pnpm run test（Vitest + Workersランタイム）とpnpm run test:react（Playwright Reactフックテスト）。
パッケージの変更にはchangesetが必要（pnpm exec changeset）。
外部PRは現在受け付けていない。チームは内部での反復を好むが、Issueや議論は歓迎。

ライセンス

MIT – パーミッシブなオープンソースライセンス。

結論 – Cloudflare Agentsは、Cloudflareエッジネットワーク上で大規模に実行可能な、状態保持型のサーバーサイドAIエージェントを構築するためのプロダクショングレードのフレームワークであり、リアルタイム同期、スケジューリング、ツール呼び出し、音声、メール、支払いなど、包括的なサポートを備えている。

cloudflare/agents