[Agents] Restructure docs

[thomasgauvin]

[MUST READ] THIS PR IS BIG BUT IT IS NOT COMPLICATED. MOST ARE FILE MOVES. ANY ADDITIONAL ITERATION OR SIGNIFICANT CHANGES, SUCH AS NEW ENTRIES WILL BE DONE IN A SEPARATE PR TO KEEP THIS PR MANAGEABLE.

Reviewer guide for this PR:

This PR is mostly an IA restructure for Agents docs. The intent is to make the diff easier to review by separating moves, new pages, and actual content changes.

Please Review: New & edited files

Net-new content in this PR:

• Home page diagram:src/components/AgentsPlatformDiagram.astro
• New Harness top level item: src/content/docs/agents/harnesses/index.mdx
• Concise tool/channel overview pages:
  • src/content/docs/agents/communication-channels/email.mdx
  • src/content/docs/agents/communication-channels/slack.mdx
  • src/content/docs/agents/tools/sandbox.mdx
  • src/content/docs/agents/tools/mcp.mdx
  • src/content/docs/agents/tools/browser.mdx

Restored / updated content:

• src/content/docs/agents/concepts/workflows.mdx → Kept as a concept page, renamed to Using Agents with Workflows.
• src/content/docs/agents/concepts/agentic-patterns/human-in-the-loop.mdx → Added back the "choosing an approach" decision guide and decision tree.

Deleted files in this PR:

• api-reference/index.mdx → Replaced by the new Runtime / Channels / Tools / MCP IA.
• getting-started/prompting.mdx → Replaced by page-level Copy/View as Markdown, Agent setup, and Docs for agents controls.
• guides/anthropic-agent-patterns.mdx → Replaced by concepts/agentic-patterns/.
• platform/prompt.txt.mdx → Replaced by page-level Copy/View as Markdown, Agent setup, and Docs for agents controls.
• platform/prompting.mdx → Replaced by page-level Copy/View as Markdown, Agent setup, and Docs for agents controls.

No Review Needed: (The rest is mostly file moves or page stubs)

These files are stubs for new indexes/page folders:

• Navigation/index stubs for the new IA. These do not need reviews. (communication-channels/index.mdx, communication-channels/chat/index.mdx, examples/index.mdx, model-context-protocol/apis/index.mdx, model-context-protocol/cloudflare/index.mdx, model-context-protocol/protocol/index.mdx, runtime/index.mdx, runtime/communication/index.mdx, runtime/execution/index.mdx, runtime/lifecycle/index.mdx, runtime/operations/index.mdx, tools/index.mdx)

These pages were moved into the new IA with minimal content changes, mostly link updates and sidebar ordering:

• api-reference/* → runtime/*, communication-channels/*, tools/*, and model-context-protocol/*
• guides/* → examples/*, communication-channels/*, runtime/*, and model-context-protocol/*
• agentic-payments/* → tools/payments/*
• model-context-protocol/* stays as model-context-protocol/*
• platform/limits.mdx stays as platform/limits.mdx
• guides/chatgpt-app.mdx moved to workers/demos/chatgpt-app.mdx
• concepts/human-in-the-loop.mdx → Consolidated into concepts/agentic-patterns/human-in-the-loop.mdx.

GitHub should show most of these as renames. The content was intentionally kept close to the original to avoid review noise.

Cross-product docs (changelogs, Workers, Cloudflare One, Workflows, etc.) that linked to old /agents/... paths have had those links updated to the new locations. These are mechanical link updates and need no content review.

Not in this PR

The new example pages for Code review agent, Payment agent, and Retrieval Augmented Generation agent were split into a follow-up PR:

#31148

[cloudflare-docs-bot]

Review

⏸️ Automatic reviews for this PR are paused.

This PR has already received 2 automatic reviews. To run another review, a codeowner can comment /review or /full-review.

Tip: Keep PRs in draft mode until they are ready for review — the bot skips draft PRs automatically.

---

⏸️ Automatic reviews for this PR are paused.

This PR has already received 2 automatic reviews. To run another review, a codeowner can comment /review or /full-review.

Tip: Keep PRs in draft mode until they are ready for review — the bot skips draft PRs automatically.

---

💡 1 suggestion found in commit e3baf35.

Suggestions (1)

File	Issue
agents/index.mdx line 19	Oxford comma — Browser, Sandbox, AI Search, MCP, Payments and other MCP tools Fix: Add a serial comma before 'and': 'Browser, Sandbox, AI Search, MCP, Payments, and other MCP tools'

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.

[thomasgauvin]

/bonk review

[ask-bonk]

A few issues to fix before merge.

Missing redirects — these old paths will 404:

• /agents/guides/
• /agents/agentic-payments/x402/charge-for-http-content/
• /agents/agentic-payments/x402/charge-for-mcp-tools/
• /agents/agentic-payments/x402/pay-from-agents-sdk/
• /agents/agentic-payments/x402/pay-with-tool-plugins/

Missing descriptions — description is required for all pages with pcx_content_type:

• src/content/docs/agents/index.mdx (overview page)
• src/content/docs/agents/harnesses/index.mdx (concept page)

Posted an inline suggestion for the harnesses page. The agents overview page frontmatter was not changed in this diff, so I cannot suggest inline — add description: Build and host AI agents on Cloudflare with durable state, real-time connections, and built-in tools. there.

[ask-bonk]

Posted a review on PR #31098.

Findings:

• Missing redirects — 5 old paths will 404 after merge:

  • /agents/guides/
  • /agents/agentic-payments/x402/charge-for-http-content/
  • /agents/agentic-payments/x402/charge-for-mcp-tools/
  • /agents/agentic-payments/x402/pay-from-agents-sdk/
  • /agents/agentic-payments/x402/pay-with-tool-plugins/

• Missing frontmatter descriptions — description is required for pages with pcx_content_type. Two key pages are missing it:

  • src/content/docs/agents/index.mdx (the main overview page)
  • src/content/docs/agents/harnesses/index.mdx (new concept page)

• Oxford comma — Missing serial comma in the agents overview intro line.

I posted inline suggestions for the harnesses description and the Oxford comma. The missing description on agents/index.mdx couldn't be suggested inline because the frontmatter wasn't part of this PR's diff.

github run