feat: expose readable state property on useAgent and AgentClient

[threepointone]

Summary

Closes #1004

Both useAgent (React) and AgentClient (vanilla JS) now expose a state property that tracks the current agent state. Previously, state was write-only via setState() — reading state required manually tracking it through the onStateUpdate callback with a separate useState. This made { ...agent.state, field: newValue } silently spread undefined, producing partial state that replaced the full server state.

• useAgent: agent.state is reactive — backed by React useState, the component re-renders when state changes from either the server or client-side setState()
• AgentClient: client.state updates synchronously on setState() and when server broadcasts arrive
• Type: State | undefined — starts undefined, populated when the server sends state on connect (from initialState) or when setState() is called
• Backward compatible: onStateUpdate callback continues to work exactly as before — the new property is additive

Before (workaround from the issue)

const [gameState, setGameState] = useState(initialState);

const agent = useAgent({
  agent: "game-agent",
  onStateUpdate: (state) => setGameState(state),
});

// Reads from separate useState, not from agent
return <div>{gameState.score}</div>;

After

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

// Read directly — reactive, no extra useState needed
return <div>{agent.state?.score}</div>;

// Spread works correctly now
agent.setState({ ...agent.state, score: agent.state.score + 10 });

Changes

Core (packages/agents/)

File	Change
src/react.tsx	Added useState for state tracking in useAgent. Updated all 3 overload signatures to include `state: State
src/client.ts	Added `state: State

Tests

File	Change
src/react-tests/useAgent.test.tsx	7 new integration tests: initial state from server, client setState tracking, server broadcast tracking, sequential updates, spread partial updates (the key use case from #1004), backward compat with onStateUpdate
src/react-tests/client.test.ts	8 new integration tests: initial undefined state, client setState, server broadcast, spread partial updates, sequential updates, simultaneous callback + property, cross-client state sync
src/tests-d/typed-use-agent.test-d.ts	Type assertion: state satisfies {} | undefined
src/tests-d/untyped-use-agent.test-d.ts	Same type assertion for untyped overload
src/tests-d/typed-agent-client.test-d.ts	Same type assertion for AgentClient

Docs (5 files)

File	Change
docs/client-sdk.md	Quick start examples show agent.state. State sync section restructured: "Reading State" → "Pushing State Updates" → "Listening for State Changes". Return value and AgentClient methods sections list state.
docs/state.md	Client-side sync section updated to show agent.state pattern. Fixed import paths (agents/react not @cloudflare/agents/react).
docs/getting-started.md	React and vanilla JS examples simplified — removed useState/onStateUpdate workaround.
docs/adding-to-existing-project.md	Same simplification.
docs/webhooks.md	Dashboard example simplified.

Examples (11 files)

All examples migrated from useState + onStateUpdate workaround to reading agent.state directly:

Example	Pattern
examples/tictactoe	const state = agent.state ?? defaultState
examples/github-webhook	Replaced repoState refs with agent.state
examples/assistant	const agents = agent.state?.agents ?? []
playground/StateDemo	Removed useState mirror, kept onStateUpdate for logging
playground/ReadonlyDemo	const state = agent.state ?? initialState
playground/SecureDemo	Same pattern, kept logging
playground/ReceiveDemo	Same pattern, kept logging
playground/RoutingDemo	const connectionCount = agent.state?.counter ?? 0
playground/PipelineDemo	const lastRun = agent.state?.lastRun ?? null
playground/WorkersDemo	Same as PipelineDemo
playground/McpClientDemo	const isConnected = !!agent.state?.connectedServer

Design decisions

1. State not reset on disconnect — agent.state retains the last known value during reconnection. The server re-sends authoritative state on reconnect via CF_AGENT_STATE, which overwrites any stale value. This prevents UI flashing. Users can check agent.identified to know if state might be stale.

2. Optimistic client updates — When setState() is called, agent.state updates immediately before the message is sent to the server. If the server rejects it (readonly connection), onStateUpdateError fires but state is already set. The server will re-send authoritative state, correcting the optimistic value.

3. State | undefined type — State starts as undefined and is populated when the server sends state on connect. This matches the existing onStateUpdate semantics and is safe with optional chaining (agent.state?.field).

Test plan

• npm run check — all 65 projects typecheck
• npm run test — all tests pass
• npm run test:react — 76 integration tests pass (15 new)
• npm run test:workers — 747 tests pass
• Type-level tests verify state type on typed/untyped useAgent and AgentClient
• Verified built .d.ts files include state: State | undefined in public API

Made with Cursor

---

[changeset-bot]

🦋 Changeset detected

Latest commit: dc45862

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agents	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1152

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1152

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1152

hono-agents

npm i https://pkg.pr.new/hono-agents@1152

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1152

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1152

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1152

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1152

commit: dc45862