まさかの state 直読み！Cloudflare Agents SDK v0.8.0 で型もスケジュールも大進化

やっほー、しぃちゃんだよ！ Cloudflare の Agents SDK が v0.8.0 にアップデートされたよ。地味に見えて、実は「あるある」な悩みをまとめて片付けてくれる内容だったから、じっくり紹介させてね。

Cloudflare Changelog developers.cloudflare.com

なにが発表されたの？

Cloudflare の Changelog に、Agents SDK v0.8.0 のリリースが載ってたよ。2026 年 3 月 23 日付けの発表で、柱になってるのはこの 4 つ。

• state をプロパティとして直接読めるようになった（React の useAgent とバニラ JS の AgentClient の両方）
• schedule() が冪等になって、Durable Object の再起動をまたいでも重複行が増えなくなった
• AgentClient に型パラメータが追加されて、TypeScript の型推論がフルで効くようになった
• 依存ライブラリが Zod 4 に移行（Zod 3 はサポート終了）

ほかにも @cloudflare/ai-chat のバグ修正、keepAlive() の実験扱い解除、@cloudflare/codemode の TanStack AI 対応もまとめて入ってるよ。

今までどうだったの？

これまでの useAgent や AgentClient は、状態を確認するのに onStateUpdate コールバックを自前で受けて、別途 state 変数に詰め替える処理が必要だったの。読みたいだけなのに、いちいち同期処理を書かされてたんだよね。

schedule() の方はもっと厄介で、onStart() みたいに Durable Object が再起動するたびに実行される場所で schedule() を呼ぶと、そのたびに新しい行が作られちゃう問題があったよ。放っておくとスケジュール行がどんどん溜まっていく、いわゆる落とし穴だったんだって。

AgentClient の方も、useAgent にはすでにあった型推論の恩恵を受けられてなくて、メソッド名の補完や引数・戻り値の型チェックが弱かったの。依存の Zod も v3 のままだったよ。

これで何が変わるの？

まず state。agent.state（React）や client.state（バニラ JS）から直接値を読めるようになって、onStateUpdate との二重管理が要らなくなったよ。state はリアクティブだから、サーバー側の変更でも setState() でのクライアント側の変更でも、勝手に再描画のトリガーになってくれるの。

schedule() は (type, callback, payload) の組み合わせで重複を判定するようになって、cron は何もしなくてもデフォルトで冪等。遅延実行や日時指定のスケジュールも、オプションを 1 個付けるだけで再起動をまたいでも行が増えなくなるよ。

AgentClient も型パラメータを渡せるようになって、RPC 呼び出しのメソッド名がオートコンプリートされて、引数と戻り値の型もちゃんと推論されるようになったの。おまけに stub というプロキシも追加されて、もっと直感的に呼べるようになったよ。

深く潜ってみよう

state を読む側のコード例はこんな感じ。

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 }

state は接続直後は undefined から始まって、サーバーが初期状態（initialState）を送ってくるか setState() が呼ばれたタイミングで値が入るよ。だから読むときはオプショナルチェーンを使うのが安全とのこと。onStateUpdate コールバックはこれまで通り動くから、既存コードを書き換える必要はないの。

schedule() の冪等オプションは、こんな風に onStart() の中で使うのが典型例。

import { Agent } from "agents";

class MyAgent extends Agent {
	async onStart() {
		// 再起動をまたいでも行は1つだけ
		await this.schedule(60, "maintenance", undefined, { idempotent: true });
	}
}

さらに、うっかり防止の仕組みも 2 つ追加されたよ。

• onStart() の中で idempotent オプションを付けずに schedule() を呼ぶと、console.warn で注意してくれる（callback ごとに 1 回だけ。cron や明示的にオプションを指定した場合はスキップ）
• 1 回のアラームサイクルで、同じ callback の使い回されなかったスケジュール行が 10 件以上溜まっていたら、console.warn に加えて診断チャンネルにイベントも発行される

型付き AgentClient のコード例はこんな感じ。

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

const value = await client.call("getValue");

await client.stub.getValue();
await client.stub.add(1, 2);

型パラメータでエージェントの型を渡すと、state の型も自動推論されるから、onStateUpdate に渡ってくる引数もちゃんと型が付くよ。型を渡さない既存コードもそのまま動くから、移行は必須じゃないの。高度な用途向けに、型ユーティリティ一式も agents/client からエクスポートされるようになったよ。

そして地味に見過ごせないのが依存関係の変更。agents、@cloudflare/ai-chat、@cloudflare/codemode がそろって Zod 4 系を要求するようになって、Zod 3 はサポート対象外になったよ。ここは今回いちばんの破壊的変更だから、アップグレード前に手元の Zod のバージョンは確認しておいた方がいいかも。

このほかの細かい改善も見逃せないよ。

• @cloudflare/ai-chat：メッセージ処理がキューイングされて、ユーザーのリクエストとツール継続処理と保存処理が同時にストリーミングされなくなった。ストップボタンを押したときにメッセージが 2 つに分裂するバグと、ツール呼び出し後にメッセージが重複するバグも修正済み
• keepAlive() と keepAliveWhile()：スケジュール行を使う方式から、メモリ上の参照カウント方式に変わって、正式に実験扱いが外れたよ。複数の呼び出し元が 1 つのアラームサイクルを共有するようになったの
• @cloudflare/codemode：新しいエントリーポイントが追加されて、Vercel AI SDK の streamText() の代わりに TanStack AI の chat() を使えるようになったよ

アップグレードは次のコマンドだけ。

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

まとめ

• state が useAgent / AgentClient のプロパティとして直接読めるようになって、onStateUpdate との二重管理が不要に
• schedule() が (type, callback, payload) で重複を判定。cron はデフォルト冪等、遅延・日時指定はオプション 1 つで明示すれば安心
• AgentClient に型パラメータを渡せるようになり、RPC 呼び出しの型推論とオートコンプリートが効くように。stub プロキシも追加
• 依存が Zod 4 に統一（Zod 3 は非対応。アップグレード時は要チェック）
• @cloudflare/ai-chat のストリーミング周りの不具合修正、keepAlive() の正式版化、@cloudflare/codemode の TanStack AI 対応もまとめて到着

Durable Objects で長生きするエージェントを Cloudflare Workers 上で運用してる人には、今日からすぐ効く実用アップデートだと思う！