docs(agents): updates for agents 0.7.0 release

[threepointone]

Summary

Documentation updates for the upcoming agents@0.7.0 release. Covers new features, API changes, and stale content that has drifted from the SDK since 0.5.0.

Note: agents@0.7.0 has not been published yet. This PR should be merged when the release ships.

Changes

1. keepAlive() / keepAliveWhile() — new API docs (schedule-tasks.mdx)

Added full documentation for the new idle-eviction prevention API (cloudflare/agents#1029, #1033):

• API reference — keepAlive() and keepAliveWhile() signatures, parameters, return types
• "Keeping the agent alive" guide section — explains the problem (DO eviction during long-running work), how the heartbeat mechanism works under the hood, multiple concurrent callers, and that AIChatAgent uses it automatically
• When-to-use table — helps users decide whether they need keepAlive() for their use case
• Marked as @experimental

2. Observability page rewrite (observability.mdx)

The entire observability page was stale — it described an old console.log-based Observability.emit() interface with incorrect event types (disconnect, message, error, queue:process). Rewrote from scratch to match the current diagnostics_channel-based implementation (cloudflare/agents#1024):

• diagnostics channels — explains the 7 named channels (agents:state, agents:rpc, agents:message, agents:schedule, agents:lifecycle, agents:workflow, agents:mcp)
• Typed subscribe() helper — from agents/observability, with type-narrowed callbacks
• Raw node:diagnostics_channel — for direct access
• Tail Workers — production observability via event.diagnosticsChannelEvents
• Custom Observability override — retained but updated with correct event types
• Complete event reference — 30+ event types across all 7 categories with payload shapes and descriptions

3. callbackHost optional for non-OAuth servers (mcp-client-api.mdx)

Updated prose and code examples to clarify that callbackHost is not needed when connecting to MCP servers that do not use OAuth (cloudflare/agents#963). Previously the examples always showed callbackHost, which could mislead users into thinking it was required.

4. MCP dedup behavior (mcp-client-api.mdx, transport.mdx)

Documented the updated addMcpServer deduplication logic:

• HTTP transport now deduplicates on both server name and URL (previously name-only)
• RPC transport continues to deduplicate by name only
• URLs are normalized before comparison (hostname case, trailing slashes, default ports)
• Documented storage accumulation behavior when same name is used with different URLs

5. agents-api.mdx quick reference table

• Added keepAlive() to the Scheduling row
• Updated Observability row from observability.emit() to subscribe(), diagnostics channels, Tail Workers

6. addToolOutput with custom denial messages (chat-agents.mdx)

Documented the output-error type and errorText field for addToolOutput, allowing custom denial messages in human-in-the-loop tool approval flows (cloudflare/agents#967).

Files changed

File	What changed
agents/api-reference/schedule-tasks.mdx	Added keepAlive(), keepAliveWhile() API ref + guide section
agents/api-reference/observability.mdx	Full page rewrite (diagnostics_channel, channels, subscribe, Tail Workers, event ref)
agents/api-reference/mcp-client-api.mdx	callbackHost clarification, dedup behavior docs
agents/model-context-protocol/transport.mdx	Updated dedup description for RPC vs HTTP
agents/api-reference/agents-api.mdx	keepAlive + observability in quick ref table
agents/api-reference/chat-agents.mdx	addToolOutput output-error/errorText docs
agents/api-reference/store-and-sync-state.mdx	Minor fix
agents/api-reference/get-current-agent.mdx	Minor fix

Related PRs (agents repo)

• #1029 — Agent.keepAlive()
• #1033 — Agent.keepAliveWhile()
• #1024 — Observability → diagnostics_channel
• #963 — callbackHost optional
• #967 — addToolOutput approval states
• #565 — RPC transport (0.6.0, dedup docs updated)
• MCP dedup name+URL change (on main, not yet released)

[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, @cloudflare/dev-plat-leads

[github-actions]

Preview URL: https://ed6540f4.preview.developers.cloudflare.com
Preview Branch URL: https://agents-070.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/agents/api-reference/observability/	https://agents-070.preview.developers.cloudflare.com/agents/api-reference/observability/
https://developers.cloudflare.com/agents/api-reference/schedule-tasks/	https://agents-070.preview.developers.cloudflare.com/agents/api-reference/schedule-tasks/
https://developers.cloudflare.com/agents/api-reference/chat-agents/	https://agents-070.preview.developers.cloudflare.com/agents/api-reference/chat-agents/
https://developers.cloudflare.com/agents/api-reference/mcp-client-api/	https://agents-070.preview.developers.cloudflare.com/agents/api-reference/mcp-client-api/
https://developers.cloudflare.com/agents/api-reference/agents-api/	https://agents-070.preview.developers.cloudflare.com/agents/api-reference/agents-api/
https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/	https://agents-070.preview.developers.cloudflare.com/agents/api-reference/store-and-sync-state/
https://developers.cloudflare.com/agents/api-reference/get-current-agent/	https://agents-070.preview.developers.cloudflare.com/agents/api-reference/get-current-agent/
https://developers.cloudflare.com/agents/model-context-protocol/transport/	https://agents-070.preview.developers.cloudflare.com/agents/model-context-protocol/transport/

[threepointone]

/bonk could you fix the build failure please

Error: 3 [ERROR] ✗ Found 2 invalid links in 1 file.
09:07:13 ▶ agents/api-reference/observability/
Error: 3 [ERROR] [starlight-links-validator-integration] An unhandled error occurred while running the "astro:build:done" hook
09:07:13 ├─ /workers/observability/tail-workers/ - invalid link
09:07:13 └─ /workers/observability/tail-workers/ - invalid link

[ask-bonk]

Fixed both invalid links in src/content/docs/agents/api-reference/observability.mdx:86 and observability.mdx:228. The path /workers/observability/tail-workers/ was missing the /logs/ segment — the correct path is /workers/observability/logs/tail-workers/.

github run