Agents SDK v0.8.0: 読み取り可能な状態、冪等スケジュール、型付きAgentClient、およびZod 4

2026年3月23日

Agents SDKの最新リリースでは、エージェントの状態を読み取り可能なプロパティとして公開し、Durable Objectの再起動時に重複するスケジュール行を防止し、AgentClientに完全なTypeScript推論を提供し、Zod 4に移行しました。

useAgentとAgentClientでの読み取り可能な状態

useAgent（React）とAgentClient（vanilla JS）の両方で、現在のエージェント状態を反映するstateプロパティが公開されるようになりました。以前は、状態を読み取るにはonStateUpdateコールバックを通じて手動で追跡する必要がありました。

React（useAgent）

JavaScript

const agent = useAgent({
  agent: "game-agent",
  name: "room-123",
});

// 状態を直接読み取り — 別途useStateとonStateUpdateは不要
return <div>Score: {agent.state?.score}</div>;

// 部分更新のためのスプレッド
agent.setState({
  ...agent.state,
  score: (agent.state?.score ?? 0) + 10
});

TypeScript

const agent = useAgent<GameAgent, GameState>({
  agent: "game-agent",
  name: "room-123",
});

// 状態を直接読み取り — 別途useStateとonStateUpdateは不要
return <div>Score: {agent.state?.score}</div>;

// 部分更新のためのスプレッド
agent.setState({
  ...agent.state,
  score: (agent.state?.score ?? 0) + 10
});

agent.stateはリアクティブです — サーバーまたはクライアント側のsetState()呼び出しから状態が変更されると、コンポーネントが再レンダリングされます。

Vanilla JS（AgentClient）

JavaScript

const client = new AgentClient({
  agent: "game-agent",
  name: "room-123",
  host: "your-worker.workers.dev",
});

client.setState({ score: 100 });
console.log(client.state); // { score: 100 }

TypeScript

const client = new AgentClient<GameAgent>({
  agent: "game-agent",
  name: "room-123",
  host: "your-worker.workers.dev",
});

client.setState({ score: 100 });
console.log(client.state); // { score: 100 }

状態は最初はundefinedで、サーバーが接続時に初期状態を送信する（initialStateから）か、setState()が呼び出されたときに設定されます。安全なアクセスのためにオプショナルチェーニング（agent.state?.field）を使用してください。

onStateUpdateコールバックは以前と同様に動作し続けます — 新しいstateプロパティは追加的なものです。

冪等なschedule()

schedule()は、（type、callback、payload）で重複を排除するidempotentオプションをサポートし、onStart()などのDurable Objectの再起動のたびに実行される場所で呼び出されたときに重複する行が蓄積されることを防ぎます。

Cronスケジュールはデフォルトで冪等です。同じコールバック、式、ペイロードでschedule("0 * * * *", "tick")を複数回呼び出すと、新しい行を作成する代わりに既存のスケジュール行を返します。オーバーライドするには{ idempotent: false }を渡してください。

遅延および日付スケジュールタイプはオプトイン冪等性をサポートします：

JavaScript

import { Agent } from "agents";

class MyAgent extends Agent {
  async onStart() {
    // 再起動時も安全 — 1つの行のみが作成される
    await this.schedule(60, "maintenance", undefined, { idempotent: true });
  }
}

TypeScript

import { Agent } from "agents";

class MyAgent extends Agent {
  async onStart() {
    // 再起動時も安全 — 1つの行のみが作成される
    await this.schedule(60, "maintenance", undefined, { idempotent: true });
  }
}

2つの新しい警告が一般的な落とし穴をキャッチするのに役立ちます：

• { idempotent: true }なしでonStart()内でschedule()を呼び出すと、実行可能なガイダンスとともにconsole.warnが出力されます（コールバックごとに1回；cronおよびidempotentが明示的に設定されている場合はスキップ）
• アラームサイクルが同じコールバックに対して10個以上の古いワンショット行を処理する場合、SDKはconsole.warnとschedule:duplicate_warning診断チャネルイベントを出力します

呼び出し推論とスタブプロキシを持つ型付きAgentClient

AgentClientは、RPC呼び出しでの完全な型推論のためのオプションのエージェント型パラメータを受け入れるようになり、useAgentですでに利用可能な型付きエクスペリエンスと一致します。

JavaScript

const client = new AgentClient({
  agent: "my-agent",
  host: window.location.host,
});

// 型付き呼び出し — メソッド名の自動補完、引数と戻り値の型が推論される
const value = await client.call("getValue");

// 型付きスタブ — 直接的なRPCスタイルプロキシ
await client.stub.getValue();
await client.stub.add(1, 2);

TypeScript

const client = new AgentClient<MyAgent>({
  agent: "my-agent",
  host: window.location.host,
});

// 型付き呼び出し — メソッド名の自動補完、引数と戻り値の型が推論される
const value = await client.call("getValue");

// 型付きスタブ — 直接的なRPCスタイルプロキシ
await client.stub.getValue();
await client.stub.add(1, 2);

状態はエージェント型から自動的に推論されるため、onStateUpdateも型付きされます：

JavaScript

const client = new AgentClient({
  agent: "my-agent",
  host: window.location.host,
  onStateUpdate: (state) => {
    // stateはMyAgentの状態型として型付きされる
  },
});

TypeScript

const client = new AgentClient<MyAgent>({
  agent: "my-agent",
  host: window.location.host,
  onStateUpdate: (state) => {
    // stateはMyAgentの状態型として型付きされる
  },
});

既存の型なし使用法は変更なしで動作し続けます。RPC型ユーティリティ（AgentMethods、AgentStub、RPCMethods）は、高度な型付けシナリオのためにagents/clientからエクスポートされるようになりました。

Zod 4への移行

agents、@cloudflare/ai-chat、@cloudflare/codemodeはzod ^4.0.0が必要になりました。Zod v3はサポートされなくなりました。

@cloudflare/ai-chatの修正

• Turnシリアライゼーション — onChatMessage()と_reply()の作業がキューに入れられ、ユーザーリクエスト、ツール継続、saveMessages()が同時にストリームされることがなくなりました
• 停止時の重複メッセージ — アクティブなストリーム中に停止をクリックしても、アシスタントメッセージが2つのエントリに分割されなくなりました
• ツール呼び出し後の重複メッセージ — 孤立したクライアントIDが永続ストレージにリークしなくなりました

keepAlive()とkeepAliveWhile()は実験的でなくなりました

keepAlive()は、スケジュール行の代わりに軽量なインメモリ参照カウントを使用するようになりました。複数の同時呼び出し元が単一のアラームサイクルを共有します。

@experimentalタグがkeepAlive()とkeepAliveWhile()の両方から削除されました。

@cloudflare/codemode: TanStack AI統合

新しいエントリポイント@cloudflare/codemode/tanstack-aiが、Vercel AI SDKのstreamText()の代替としてTanStack AIのchat()のサポートを追加しました：

JavaScript

import {
  createCodeTool,
  tanstackTools,
} from "@cloudflare/codemode/tanstack-ai";
import { chat } from "@tanstack/ai";

const codeTool = createCodeTool({
  tools: [tanstackTools(myServerTools)],
  executor,
});

const stream = chat({
  adapter,
  tools: [codeTool],
  messages
});

TypeScript

import {
  createCodeTool,
  tanstackTools
} from "@cloudflare/codemode/tanstack-ai";
import { chat } from "@tanstack/ai";

const codeTool = createCodeTool({
  tools: [tanstackTools(myServerTools)],
  executor,
});

const stream = chat({
  adapter,
  tools: [codeTool],
  messages
});

アップグレード

最新バージョンに更新するには：

npm i agents@latest @cloudflare/ai-chat@latest