agents-sdk

Cloudflare Agents SDK

Agents SDK に関する知識が古くなっている可能性があります。Agents SDK のタスクでは、事前学習よりも情報の取得を優先してください。

情報の取得元

Cloudflare のドキュメント：https://developers.cloudflare.com/agents/index.md

トピック	ドキュメント URL	用途
はじめに	クイックスタート	最初のエージェント、プロジェクトのセットアップ
既存プロジェクトへの追加	既存プロジェクトへの追加	既存の Workers アプリへのインストール
設定	設定	wrangler.jsonc、バインディング、アセット、デプロイ
Agent クラス	Agents API	エージェントのライフサイクル、パターン、注意点
状態	状態の保存と同期	setState、validateStateChange、永続化
ルーティング	ルーティング	URL パターン、routeAgentRequest
呼び出し可能なメソッド	呼び出し可能なメソッド	@callable、RPC、ストリーミング、タイムアウト
スケジュール	タスクのスケジュール	schedule()、scheduleEvery()、cron
ワークフロー	ワークフローの実行	AgentWorkflow、永続的な複数ステップのタスク
HTTP／WebSocket	WebSocket	ライフサイクルフック、休止
チャットエージェント	チャットエージェント	AIChatAgent、ストリーミング、ツール、永続化
クライアント SDK	クライアント SDK	useAgent、AgentClient、状態、RPC、HTTP
クライアントツール	クライアントツール	クライアント側のツール、autoContinueAfterToolResult
サーバー主導のメッセージ	自律的な応答	saveMessages、waitUntilStable、サーバー起点のターン
再開可能なストリーミング	チャットエージェント	切断後のストリーム復旧
メール	メール	メールのルーティング、安全な返信リゾルバー
MCP クライアント	MCP クライアント	MCP サーバーへの接続
MCP サーバー	MCP サーバー	createMcpHandler を使った MCP サーバーの構築
MCP トランスポート	MCP トランスポート	Streamable HTTP、SSE、RPC トランスポートのオプション
MCP サーバーの保護	MCP の保護	OAuth、プロキシ MCP、セキュリティ強化
Human-in-the-loop	Human-in-the-loop	ワークフローの承認、情報の引き出し、タイムアウト処理
永続的な実行	永続的な実行	runFiber()、stash()、DO の退避後も実行を継続
キュー	キュー	組み込みの FIFO キュー、queue()
再試行	再試行	this.retry()、バックオフ／ジッター
オブザーバビリティ	オブザーバビリティ	diagnostics-channel イベント
プッシュ通知	プッシュ通知	エージェントからの Web Push ＋ VAPID
Webhook	Webhook	外部 Webhook の受信
クロスドメイン認証	クロスドメイン認証	WebSocket 認証、トークン、CORS
読み取り専用接続	読み取り専用	shouldConnectionBeReadonly
音声	音声	実験的な STT／TTS、withVoice
Web の閲覧	ブラウザツール	実験的な CDP ブラウザー自動化
Think	Think	実験的な高レベルのチャットエージェントクラス
移行	AI SDK v5、AI SDK v6	@cloudflare/ai-chat のアップグレード

機能

Agents SDK では、次の機能を利用できます。

• 永続化された状態 — SQLite による状態管理。setState を介してクライアントに自動同期されます
• 呼び出し可能な RPC — WebSocket 経由で呼び出される @callable() メソッド
• スケジュール設定 — 1 回限り、繰り返し（scheduleEvery）、cron タスク
• ワークフロー — AgentWorkflow による、複数ステップの耐久性のあるバックグラウンド処理
• 耐久性のある実行 — DO のエビクション後も継続する作業のための runFiber() / stash()
• キュー — queue() による、再試行機能を備えた組み込みの FIFO キュー
• 再試行 — 指数バックオフとジッターを使う this.retry()
• MCP 統合 — MCP サーバーへの接続、または createMcpHandler を使った独自の MCP サーバーの構築
• メール処理 — 安全なルーティングによるメールの受信と返信
• ストリーミングチャット — 再開可能なストリーム、メッセージの永続化、ツールを備えた AIChatAgent
• サーバー駆動メッセージ — エージェントのプロアクティブなターンのための saveMessages、waitUntilStable
• React フック — クライアントアプリ向けの useAgent、useAgentChat
• 可観測性 — 状態、RPC、スケジュール、ライフサイクルの diagnostics_channel イベント
• プッシュ通知 — エージェントからの Web Push + VAPID 配信
• Webhook — 外部 Webhook の受信と検証
• 音声（実験的）— @cloudflare/voice による STT/TTS
• ブラウザツール（実験的）— agents/browser による CDP を利用したブラウジング
• Think（実験的）— @cloudflare/think による、より高レベルなチャットエージェント

まず、インストールを確認する

npm ls agents  # Should show agents package

インストールされていない場合：

npm install agents

チャットエージェントの場合：

npm install agents @cloudflare/ai-chat ai @ai-sdk/react

Wrangler の設定

{
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
}

注意事項：

• tsconfig で experimentalDecorators を有効にしないでください（@callable が動作しなくなります）
• 古いマイグレーションは編集せず、常に新しいタグを追加してください
• 各エージェントクラスには、それぞれ専用の DO バインディングとマイグレーションエントリが必要です
• Workers AI では "ai": { "binding": "AI" } を追加してください

エージェントクラス

import { Agent, routeAgentRequest, callable } from "agents";

type State = { count: number };

export class Counter extends Agent<Env, State> {
  initialState = { count: 0 };

  validateStateChange(nextState: State, source: Connection | "server") {
    if (nextState.count < 0) throw new Error("Count cannot be negative");
  }

  onStateUpdate(state: State, source: Connection | "server") {
    console.log("State updated:", state);
  }

  @callable()
  increment() {
    this.setState({ count: this.state.count + 1 });
    return this.state.count;
  }
}

export default {
  fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
};

ルーティング

リクエストは /agents/{agent-name}/{instance-name} にルーティングされます。

クラス	URL
Counter	/agents/counter/user-123
ChatRoom	/agents/chat-room/lobby

クライアント：useAgent({ agent: "Counter", name: "user-123" })

カスタムルーティング：getAgentByName(env.MyAgent, "instance-id") を使用し、その後 agent.fetch(request) を呼び出します。

コア API

タスク	API
状態を読み取る	this.state.count
状態を書き込む	this.setState({ count: 1 })
SQL クエリ	this.sql`SELECT * FROM users WHERE id = ${id}`
スケジュール設定（遅延）	await this.schedule(60, "task", payload)
スケジュール設定（cron）	await this.schedule("0 * * * *", "task", payload)
スケジュール設定（間隔）	await this.scheduleEvery(30, "poll")
RPC メソッド	@callable() myMethod() { ... }
ストリーミング RPC	@callable({ streaming: true }) stream(res) { ... }
ワークフローを開始する	await this.runWorkflow("ProcessingWorkflow", params)
耐久性のあるファイバー	await this.runFiber("name", async (ctx) => { ... })
作業をキューに追加する	this.queue("handler", payload)
バックオフを伴う再試行	await this.retry(fn, { maxAttempts: 5 })
クライアントにブロードキャストする	this.broadcast(message)
接続を取得する	this.getConnections(tag?)

React クライアント

クライアントの選択方法と現在の接続例については、client-sdk.md をお読みください。チャット UI とツールについては、streaming-chat.md もお読みください。

参考資料

コア

• references/state-scheduling.md — 状態の永続化、スケジュール設定、SQL
• references/callable.md — RPC メソッド、ストリーミング、タイムアウト
• references/routing.md — URL パターン、カスタムルーティング、getAgentByName
• references/configuration.md — Wrangler の設定、バインディング、Vite のセットアップ

チャットとストリーミング

• references/streaming-chat.md — AIChatAgent、再開可能なストリーム、ツール
• references/client-sdk.md — useAgent、useAgentChat、AgentClient
• references/server-driven-messages.md — トリガーパターン、saveMessages
• references/human-in-the-loop.md — 承認フロー、needsApproval

バックグラウンド処理

• references/workflows.md — Durable Workflows の統合
• references/durable-execution.md — runFiber、stash、エビクション後も存続
• references/queue-retries.md — 組み込みキュー、バックオフを伴う再試行

インテグレーション

• references/mcp.md — MCP クライアントとサーバー、トランスポート、セキュリティ保護
• references/email.md — メールのルーティングと処理
• references/webhooks-push.md — Webhook、プッシュ通知
• references/observability.md — Diagnostics-channel イベント

実験的機能

• references/think.md — @cloudflare/think の高レベルなチャットエージェント
• references/voice.md — @cloudflare/voice の STT/TTS
• references/codemode.md — ツールオーケストレーションのための Code Mode
• references/browse-the-web.md — CDP ブラウザツール