docs/tests/enhancements

[threepointone]

Summary

This PR adds comprehensive documentation for the Agents SDK and implements several feature improvements across state management, MCP, routing, scheduling, and the callable RPC system.

Highlights:

• 15+ new documentation files covering core concepts and features
• 10+ new test files with 100+ tests
• New features: synchronous setState(), validateStateChange() hook, scheduleEvery(), basePath routing, server-sent identity, callable improvements
• No breaking changes (backward compatibility maintained)

---

Documentation Added

Documentation Index

File	Description
docs/index.md	Main table of contents organizing all documentation by category

Getting Started & Integration

File	Description
docs/getting-started.md	Quick start guide covering installation, first agent, state basics, and deployment
docs/adding-to-existing-project.md	Guide for integrating agents into existing Workers, including React apps, Hono, static assets, and common patterns

Core Concepts

File	Description
docs/state.md	State management covering initialState, setState(), validateStateChange(), onStateUpdate(), persistence, and client synchronization
docs/routing.md	URL routing patterns, routeAgentRequest(), custom paths with basePath, server-sent identity, and advanced routing scenarios
docs/http-websockets.md	HTTP/WebSocket lifecycle hooks (onRequest, onConnect, onMessage, onClose), connection management, per-connection state, hibernation, and common patterns

Features

File	Description
docs/callable-methods.md	@callable decorator, RPC over WebSocket, streaming responses, TypeScript integration, error handling, and when to use DO RPC instead
docs/mcp-client.md	Connecting to MCP servers with addMcpServer(), OAuth flows, transport options, and tool usage
docs/scheduling.md	One-time, recurring (scheduleEvery), and cron-based scheduling

---

New Features

State Management

Synchronous setState() - setState() is now synchronous, returning void instead of Promise<void>. Existing code using await this.setState(...) continues to work.

// Before (still works - awaiting void is harmless)
await this.setState({ count: 1 });

// After (preferred)
this.setState({ count: 1 });

validateStateChange() hook - New synchronous validation hook that runs before state is persisted and broadcast. Throw to reject updates:

validateStateChange(nextState: State, source: Connection | "server") {
  if (nextState.count < 0) {
    throw new Error("Count cannot be negative");
  }
}

onStateUpdate() is now non-gating - Runs via ctx.waitUntil() after persistence and broadcast. Errors are routed to onError() but don't prevent state updates.

Execution order:

1. validateStateChange(nextState, source) - validation (sync, gating)
2. State persisted to SQLite
3. State broadcast to connected clients
4. onStateUpdate(nextState, source) - notifications (async via ctx.waitUntil, non-gating)

Scheduling

scheduleEvery(intervalSeconds, callback, payload?) - Fixed-interval recurring tasks with overlap prevention and error resilience.

await this.scheduleEvery(60, "cleanup");
await this.scheduleEvery(300, "syncData", { source: "api" });

• Validates interval doesn't exceed 30 days (DO alarm limit)
• Overlap prevention with hung callback detection (configurable via hungScheduleTimeoutSeconds)

MCP Server API

Options-based addMcpServer() overload - Cleaner API avoiding positional undefined parameters.

// New preferred format
await this.addMcpServer("server", url, {
  callbackHost: "https://my-worker.workers.dev",
  transport: { headers: { Authorization: "Bearer ..." } }
});

Custom Routing

• basePath - Bypass default URL construction for custom routing
• path - Append sub-paths to routes
• Server-sent identity - Agents send name and agent type on connect
• onIdentity / onIdentityChange - Callbacks for identity events
• identified / ready - State for identity status
• static options = { sendIdentityOnConnect } - Server-side control

const agent = useAgent({
  basePath: "user",
  onIdentity: (name, agentType) => console.log(`Connected to ${name}`)
});

Callable System Improvements

• Client-side RPC timeout - { timeout: 5000 }
• StreamingResponse.error(message) - Graceful stream error signaling
• getCallableMethods() - Introspection API for callable methods
• Connection close handling - Pending calls rejected on disconnect
• WeakMap for metadata - Prevents memory leaks
• crypto.randomUUID() - More robust RPC IDs
• Streaming observability - Events for streaming calls
• Streaming error logging - Server-side errors now logged for observability

// New format (supports timeout)
await agent.call("method", [args], {
  timeout: 5000,
  stream: { onChunk, onDone, onError }
});

// Legacy format (still supported)
await agent.call("method", [args], { onChunk, onDone, onError });

Email Utilities

• isAutoReplyEmail(headers) - Detect auto-reply emails using standard RFC headers (Auto-Submitted, X-Auto-Response-Suppress, Precedence)

---

Tests Added

File	Coverage
packages/agents/src/tests/state.test.ts	State persistence, sync, validation, edge cases
packages/agents/src/tests/basepath.test.ts	Custom path routing
packages/agents/src/tests/routing.test.ts	General routing (22 tests)
packages/agents/src/tests/callable.test.ts	RPC, streaming, errors, introspection (17 tests)
packages/agents/src/tests/client-timeout.test.ts	Client-side RPC timeouts
packages/agents/src/tests/message-handling.test.ts	WebSocket message handling
packages/agents/src/tests/email-headers.test.ts	Email header utilities
packages/agents/src/tests/mcp/add-mcp-server.test.ts	MCP options API, legacy signature

---

Bug Fixes

• React useRef type fix - Fixed type error in react.tsx
• Memory leak prevention - WeakMap for callable metadata storage
• Connection cleanup - Pending RPC calls rejected on WebSocket close
• JSON parse error handling - Graceful fallback to initialState on corrupted state
• Streaming error logging - Server-side errors in streaming methods are now logged

---

Reviewer Notes

Key Areas for Review

1. State Management (packages/agents/src/index.ts)

   • Synchronous setState() refactor
   • validateStateChange() hook
   • onStateUpdate() via ctx.waitUntil()

2. Routing & Identity (packages/agents/src/index.ts, client.ts, react.tsx)

   • New CF_AGENT_IDENTITY WebSocket message type
   • Client state management for identity
   • static options pattern for server-side configuration

3. Callable System (packages/agents/src/client.ts)

   • Backward compatibility detection for streaming options
   • Timeout implementation with cleanup

4. Schema Migration (scheduleEvery)

   • Adds intervalSeconds, running, and execution_started_at columns to cf_agents_schedules
   • Auto-migrates existing agents

Test Commands

# Run all tests
CI=true npm test

# Run specific test files
cd packages/agents && npm run test:workers -- callable.test.ts
cd packages/agents && npm run test:workers -- routing.test.ts
cd packages/agents && npm run test:workers -- state.test.ts

Changesets

• .changeset/sync-set-state.md - Synchronous setState refactor
• .changeset/callable-improvements.md - Callable system enhancements
• .changeset/identity-routing-enhancements.md - Routing and identity features
• .changeset/friendly-mcp-options.md - MCP options API
• .changeset/cool-intervals-run.md - scheduleEvery method
• .changeset/email-header-utilities.md - Email header utilities
• .changeset/fix-serializable-interface-types.md - Serializable type fixes
• .changeset/bug-fixes-three.md - Bug fixes

[changeset-bot]

🦋 Changeset detected

Latest commit: 29b9fdd

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

This PR includes changesets to release 1 package

Name	Type
agents	Patch

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

npm i https://pkg.pr.new/cloudflare/agents@812

commit: 29b9fdd

[threepointone]

@craigsdennis you wanted this

[threepointone]

@mattzcarey better, no?

[whoiskatrin]

i am actually a fan of this, i like it, it's clean

[threepointone]

@whoiskatrin ramp wanted this