Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

Agents API

最終更新 Markdown で表示Agent セットアップ

このページは Agents SDK の概要です。各機能の詳細は、リンク先のリファレンスを参照してください。

概要

Agents SDK は、次の 2 つの主要な API を提供します。

API 説明
サーバー側 の Agent クラス 接続、状態、メソッド、AI モデル、エラー処理など、エージェントのロジックをまとめます
クライアント側 SDK ブラウザーから接続するための AgentClient、useAgent、useAgentChat

Agent クラス

Agent は、基底の Agent クラスを継承したクラスです。

import { Agent, routeAgentRequest } from "agents";

export class MyAgent extends Agent<Env, State> {
	// Your agent logic
}

export default {
	async fetch(request: Request, env: Env) {
		return (
			(await routeAgentRequest(request, env)) ||
			new Response("Not found", { status: 404 })
		);
	},
} satisfies ExportedHandler<Env>;

各 Agent は数百万のインスタンスを持てます。各インスタンスは独立して動く小さなサーバーで、水平スケールできます。インスタンスは一意の識別子（ユーザー ID、メール、チケット番号など）で指定します。

ライフサイクル

flowchart TD
    A["onStart<br/>（インスタンスが起動）"] --> B["onRequest<br/>（HTTP）"]
    A --> C["onConnect<br/>（WebSocket）"]
    A --> D["onEmail"]
    C --> E["onMessage ↔ send()<br/>onError（失敗時）"]
    E --> F["onClose"]
メソッド 実行タイミング
onStart(props?) インスタンスの起動時、またはハイバーネーションからの復帰時。getAgentByName または routeAgentRequest 経由で渡した任意の 初期化 props を受け取ります。
onRequest(request) インスタンスへの HTTP リクエストごと
onConnect(connection, ctx) WebSocket 接続が確立したとき
onMessage(connection, message) WebSocket メッセージを受信するたび
onError(connection, error) WebSocket エラーが発生したとき
onClose(connection, code, reason, wasClean) WebSocket 接続が閉じたとき
onEmail(email) メールがインスタンスへルーティングされたとき
onStateChanged(state, source) 状態が変わったとき（サーバーまたはクライアントから）

コアプロパティ

プロパティ 型 説明
this.env Env 環境変数とバインディング
this.ctx ExecutionContext リクエストの実行コンテキスト
this.state State 現在の永続化された状態
this.sql Function 組み込み SQLite で SQL クエリを実行します

サーバー側 API リファレンス

機能 メソッド ドキュメント
状態 setState()、onStateChanged()、initialState 状態の保存と同期
呼び出し可能なメソッド @callable() デコレーター 呼び出し可能なメソッド
スケジュール schedule()、scheduleEvery()、getScheduleById()、listSchedules() タスクのスケジュール
耐久実行 runFiber()、startFiber()、stash()、onFiberRecovered()、keepAlive()、keepAliveWhile() 耐久実行
キュー queue()、dequeue()、dequeueAll()、getQueue() タスクのキュー
WebSockets onConnect()、onMessage()、onClose()、broadcast() WebSockets
HTTP/SSE onRequest() HTTP と SSE
メール onEmail()、replyToEmail() メールルーティング
Workflows runWorkflow()、waitForApproval() Workflows の実行
MCP Client addMcpServer()、removeMcpServer()、getMcpServers() MCP Client API
AI モデル Workers AI、OpenAI、Anthropic のバインディング AI モデルの利用
プロトコルメッセージ shouldSendProtocolMessages()、isConnectionProtocolEnabled() プロトコルメッセージ
コンテキスト getCurrentAgent() getCurrentAgent()
トレーシング wrapAISDK() トレーシング
診断チャネル subscribe()、診断チャネル 診断チャネル
サブエージェント subAgent()、abortSubAgent()、deleteSubAgent() サブエージェント
ツールとしてのエージェント runAgentTool()、clearAgentToolRuns()、hasAgentToolRun() ツールとしてのエージェント
Agent Skills skills レジストリ、バンドルされたスキルソース、スクリプトランナー Agent Skills
セッション Session.create()、コンテキストブロック、コンパクション、検索 セッション
Think Think 基底クラス、ワークスペースツール、ライフサイクルフック、拡張 Think
Chat SDK createChatSdkState()、ChatSdkStateAgent Chat SDK

SQL API

各 Agent インスタンスは、this.sql 経由でアクセスする組み込み SQLite データベースを持ちます。

// Create tables
this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`;

// Insert data
this.sql`INSERT INTO users (id, name) VALUES (${id}, ${name})`;

// Query data
const users = this.sql<User>`SELECT * FROM users WHERE id = ${id}`;

クライアントと同期する状態には、代わりに State API を使います。

クライアント側 API リファレンス

機能 メソッド ドキュメント
WebSocket クライアント AgentClient クライアント SDK
HTTP クライアント agentFetch() クライアント SDK
React フック useAgent() クライアント SDK
チャットフック useAgentChat() クライアント SDK
エージェントツールイベント useAgentToolEvents() ツールとしてのエージェント

モジュールレベルのヘルパーとして、agents/agent-tools の agentTool() があります。Think または AIChatAgent のサブクラスを AI SDK のツール定義に変換します。

簡単な例

import { useAgent } from "agents/react";
import type { MyAgent } from "./server";

function App() {
	const agent = useAgent<MyAgent, State>({
		agent: "my-agent",
		name: "user-123",
	});

	// Call methods on the agent
	agent.stub.someMethod();

	// Update state (syncs to server and all clients)
	agent.setState({ count: 1 });
}

チャットエージェント

AI チャットアプリでは、Agent ではなく AIChatAgent を継承します。

import { AIChatAgent } from "@cloudflare/ai-chat";

class ChatAgent extends AIChatAgent {
	async onChatMessage(onFinish) {
		// this.messages contains the conversation history
		// Return a streaming response
	}
}

機能は次のとおりです。

  • 組み込みのメッセージ永続化
  • 自動で再開可能なストリーミング（ストリーム途中での再接続）
  • useAgentChat React フックと連携

完全なチュートリアルは チャットエージェントを構築する を参照してください。

ルーティング

Agents には、次の URL パターンでアクセスします。

https://your-worker.workers.dev/agents/:agent-name/:instance-name

Worker では routeAgentRequest() でリクエストを振り分けます。

import { routeAgentRequest } from "agents";

export default {
	async fetch(request: Request, env: Env) {
		return (
			routeAgentRequest(request, env) ||
			new Response("Not found", { status: 404 })
		);
	},
} satisfies ExportedHandler<Env>;

カスタムパス、CORS、インスタンス名のパターンは ルーティング を参照してください。

次のステップ

設定

wrangler.jsonc のセットアップとデプロイについて学びます。

WebSockets

クライアントとのリアルタイム双方向通信です。

役に立ちましたか？