Agents SDK

Page content

Cloudflare の Agents SDK（旧称: AI Agent Starter Kit）の使い方を解説します。

Cloudflare Agents SDK とは

通常のAIアプリはステートレスですが、Agents SDKを使うと「会話を記憶し、スケジュールで動き、ツールを呼び出し、他のエージェントと連携し、ユーザーとリアルタイムでつながる」本格的なエージェントを構築できます。各エージェントは Durable Object 上で動作し、独自のSQLデータベース・WebSocket接続・スケジューリング機能を持ちます。

🚀 クイックスタート（3コマンドで動く）

1. テンプレートからプロジェクト作成

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

2. 依存関係インストール＆起動

cd agents-starter
npm install
npm run dev

http://localhost:5173 を開くとエージェントが動いているのを確認できます。デフォルトでは Workers AI を使うため、APIキーは不要です。

📁 プロジェクト構成

ファイル 役割
src/server.ts チャットエージェントのロジック・ツール定義
src/app.tsx React製チャットUI
src/client.tsx Reactエントリポイント
src/styles.css Tailwind + Kumo スタイル

🛠 主な機能

スターターには以下が含まれています。

  • ストリーミングAIチャット（Workers AI経由）
  • 3種のツールパターン：サーバーサイド自動実行・クライアントサイド（ブラウザ）・Human-in-the-loop（承認フロー）
  • スケジューリング：一回限り・遅延実行・定期（cron）タスク
  • 推論表示：モデルの思考過程をストリーミング表示

🤖 別のAIモデルに切り替える

server.ts のモデル部分を変更するだけで他のプロバイダーも使えます。

Anthropic Claude を使う場合：

import { anthropic } from "@ai-sdk/anthropic";

const result = streamText({
  model: anthropic("claude-sonnet-4-20250514"),
  // ...
});

OpenAI を使う場合：

import { openai } from "@ai-sdk/openai";

const result = streamText({
  model: openai("gpt-4o"),
});

既存プロジェクトに追加する場合

既存のWorkersプロジェクトに追加する場合は、agentsパッケージを直接インストールして、最初のエージェントを定義できます。

npm i agents

import { Agent } from "agents";

export class MyAgent extends Agent<Env> {
  // this.state でステート管理
  // this.sql でSQLクエリ実行
}

📦 バージョン情報

2025年12月にリリースされた Agents SDK v0.3.0 では AI SDK v6 への完全対応、統合ツールパターン、動的ツール承認、強化されたReact Hooksなどが追加されています。

インストールコマンド：

npm install agents@^0.3.0 workers-ai-provider@^3.0.0 ai@^6.0.0 @ai-sdk/react@^3.0.0

🌐 デプロイ

npm run deploy

デプロイ後、エージェントはCloudflareのグローバルネットワーク上で <name>.<subdomain>.workers.dev というURLで公開されます。wrangler.jsonc の name フィールドがURLになります。

参考リンク