Sync Agents SDK documentation from PR #812

[agents-git-bot]

Summary

This PR syncs documentation updates from cloudflare/agents PR #812 (docs/tests/enhancements) to the Cloudflare developer documentation.

Source PR: cloudflare/agents#812

Approach

This PR updates existing documentation files in the cloudflare-docs repository rather than creating new files, ensuring continuity with the current documentation structure.

Files Updated

State Management (api-reference/store-and-sync-state.mdx)

• Document synchronous setState() (no longer returns Promise)
• Add validateStateChange() hook for synchronous validation
• Clarify onStateUpdate() is non-gating (runs via queueMicrotask)
• Document state update execution order: validateStateChange → persist → broadcast → onStateUpdate
• Add section on understanding the source parameter
• Document state serialization requirements

Callable Methods (api-reference/calling-agents.mdx)

• Add comprehensive @callable decorator documentation
• Document client-side RPC timeout option: agent.call("method", [], { timeout: 5000 })
• Add stream.error() method for graceful error handling
• Document getCallableMethods() introspection API
• Document connection close handling for pending calls
• Enhance streaming documentation with new options format
• Add TypeScript integration examples

Scheduling (api-reference/schedule-tasks.mdx)

• Add scheduleEvery() method for fixed-interval recurring tasks
• Document overlap prevention and error resilience
• Add comparison table: interval vs cron scheduling
• Document validation (interval must be >0 and ≤30 days)
• Add comprehensive API reference section
• Update Schedule type to include "interval" discriminated union

MCP Client (model-context-protocol/mcp-client-api.mdx)

• Document new options-based addMcpServer() API
• Show cleaner syntax avoiding positional undefined parameters
• Add comparison examples: new format vs legacy format
• Note legacy signature still supported for backward compatibility

Key Features from PR #812

State Management

• Synchronous setState - Returns void instead of Promise (backward compatible)
• validateStateChange hook - Synchronous validation that runs before persistence and broadcast
• onStateUpdate is non-gating - Runs via queueMicrotask after state is persisted and broadcast

Scheduling

• scheduleEvery() - Fixed-interval recurring tasks with overlap prevention
• Validates interval does not exceed 30 days (DO alarm limit)
• Built-in hung callback detection

Callable System

• Client-side RPC timeout - Reject calls that do not complete in time
• stream.error() - Graceful stream error signaling
• getCallableMethods() - Introspection API for callable methods
• Connection close handling - Pending calls rejected on disconnect

MCP

• Options-based API - Cleaner addMcpServer() signature

Style Guidelines Applied

All updates follow Cloudflare documentation standards:

• ✅ <TypeScriptExample> components for all TypeScript code blocks
• ✅ <WranglerConfig> components for wrangler configuration examples
• ✅ Full relative links with trailing slashes (/agents/configuration/)
• ✅ No contractions or exclamation marks
• ✅ Professional, technical tone
• ✅ Proper component imports

Testing

Documentation changes have been validated for:

1. Proper MDX formatting and component usage
2. Technical accuracy against source PR
3. Consistency with Cloudflare docs style guide
4. Code example validity

🤖 Generated with Claude Code

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/agents/	@irvinebroque, @rita3ko, @elithrar, @thomasgauvin, @threepointone, @whoiskatrin, @cloudflare/pcx-technical-writing, @cloudflare/ai-agents

[github-actions]

Preview URL: https://aa1f0cee.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-812.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/agents/api-reference/calling-agents/	https://sync-docs-pr-812.preview.developers.cloudflare.com/agents/api-reference/calling-agents/
https://developers.cloudflare.com/agents/api-reference/schedule-tasks/	https://sync-docs-pr-812.preview.developers.cloudflare.com/agents/api-reference/schedule-tasks/

[agents-git-bot]

Documentation sync updated with latest changes from cloudflare/agents#812.

Changes in this update:

• Added scheduleEvery() documentation for fixed-interval scheduling
• Added custom URL routing with basePath and server-sent identity documentation
• Added callable system enhancements (timeout, StreamingResponse.error(), getCallableMethods())
• Added MCP options-based API documentation

All changes have been committed and pushed to the sync-docs-pr-812 branch.

[agents-git-bot]

Documentation Sync Update

This PR has been updated with comprehensive documentation changes from cloudflare/agents PR #812.

Changes Synced

1. Scheduling Documentation (schedule-tasks.mdx)

• Added documentation for new scheduleEvery() method
• Documented fixed-interval recurring tasks with sub-minute precision
• Explained overlap prevention behavior
• Documented error resilience
• Added practical examples and use cases

2. Routing & Identity Documentation (calling-agents.mdx)

• Added "Custom URL routing with basePath" section
• Documented the new basePath option for custom URL patterns
• Added "Server-sent identity" section with:
  • onIdentity callback documentation
  • onIdentityChange callback for reconnection scenarios
  • Identity state properties (identified, ready promise)
  • Server-side control with sendIdentityOnConnect option
• Included comprehensive client and server-side examples

3. Callable Methods Documentation (agents-api.mdx)

• Added complete "Callable methods" section covering:
  • @callable decorator usage and syntax
  • Client-side RPC with agent.call() and agent.stub
  • New timeout option for RPC calls
  • Streaming with StreamingResponse
  • New StreamingResponse.error() method for graceful error handling
  • getCallableMethods() introspection API
  • Connection close handling for pending calls
  • Comprehensive examples for both regular and streaming methods

4. MCP Client Documentation (mcp-client-api.mdx)

• Updated addMcpServer() documentation
• Documented new options-based API as recommended approach
• Maintained backward compatibility documentation for legacy 5-parameter signature
• Added migration guide with before/after examples
• Clarified all available options (callbackHost, agentsPrefix, client, transport)

Documentation Style Compliance

All changes follow Cloudflare documentation standards:

• Uses TypeScriptExample component for code blocks
• No contractions or exclamation marks
• Proper use of :::note callouts
• Clear, professional technical language
• Comprehensive practical examples

Total Changes

• 4 files modified
• 1112 lines added
• All new features from PR Fix typo on Logpush overview page #812 comprehensively documented

The documentation is ready for review and aligns with the source PR at cloudflare/agents#812

[agents-git-bot]

Updated Documentation Sync

This PR has been updated with comprehensive documentation from cloudflare/agents PR 812.

Files Updated (6 total)

1. api-reference/calling-agents.mdx - Updated with streaming improvements, introspection API, timeout support
2. api-reference/routing.mdx - NEW FILE with custom routing, basePath, identity features
3. api-reference/schedule-tasks.mdx - Updated with scheduleEvery(), intervals, AI-assisted scheduling
4. api-reference/store-and-sync-state.mdx - Updated with workflow integration, patterns
5. api-reference/websockets.mdx - Updated with per-connection state, tags, lifecycle
6. model-context-protocol/mcp-client-api.mdx - Updated with options-based API

Key New Features Documented

• scheduleEvery() method for interval-based scheduling with overlap prevention
• Custom routing with basePath and path options
• Server-sent identity with onIdentity/onIdentityChange callbacks
• Streaming callback format change (stream parameter first)
• getCallableMethods() introspection API
• Client-side RPC timeout support
• Options-based addMcpServer() API
• Per-connection state with connection.setState()
• Connection tags
• Enhanced lifecycle documentation

Style Compliance

All files follow Cloudflare documentation standards:

• ✅ TypeScriptExample components for all code blocks
• ✅ Proper frontmatter with title, pcx_content_type, sidebar
• ✅ No contractions or exclamation marks
• ✅ Full relative links with trailing slashes
• ✅ Meaningful link text
• ✅ Component imports after frontmatter

Commit: 4f04222
Source PR: cloudflare/agents#812

[agents-git-bot]

Updated Documentation Sync

This PR has been updated with documentation changes from cloudflare/agents#812.

Changes in this update:

Schedule Tasks (/agents/api-reference/schedule-tasks/)

• Added documentation for new scheduleEvery() method for fixed-interval recurring tasks
• Documented interval vs cron differences (sub-minute precision, overlap prevention)
• Added examples showing interval scheduling patterns

Calling Agents (/agents/api-reference/calling-agents/)

• Added custom routing documentation with basePath option
• Documented server-sent identity features for custom routing scenarios
• Added onIdentity and onIdentityChange callback documentation
• Documented security option to disable identity sending
• Added path option for sub-path routing

Key Features Documented:

1. Interval Scheduling - scheduleEvery() for tasks that run at fixed intervals with automatic overlap prevention
2. Custom Routing - basePath for clean URLs without /agents/ prefix, with server-determined instance names
3. Identity Management - Server-sent identity, identity change handling, and security controls
4. Sub-path Routing - Additional path segments with the path option

All documentation follows Cloudflare docs style guidelines including proper use of components and formatting.

[github-actions]

CI run failed: build logs