[Agents] Restructure docs#31098
Open
thomasgauvin wants to merge 2 commits into
Open
Conversation
Review⏸️ Automatic reviews for this PR are paused. This PR has already received 2 automatic reviews. To run another review, a codeowner can comment
⏸️ Automatic reviews for this PR are paused. This PR has already received 2 automatic reviews. To run another review, a codeowner can comment
💡 1 suggestion found in commit Suggestions (1)
CommandsOnly codeowners can run commands. Post a comment with the command to trigger it.
|
Contributor
Author
|
/bonk review |
thomasgauvin
commented
May 30, 2026
Contributor
There was a problem hiding this comment.
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.
| } from "~/components"; | ||
|
|
||
| Most AI applications today are stateless — they process a request, return a response, and forget everything. Real agents need more. They need to remember conversations, act on schedules, call tools, coordinate with other agents, and stay connected to users in real-time. The Agents SDK gives you all of this as a TypeScript class. | ||
| Build and host Agents on Cloudflare, connect chat, voice, email, Slack, and webhooks to a durable agent runtime with Browser, Sandbox, AI Search, MCP, Payments and other MCP tools. |
Contributor
There was a problem hiding this comment.
Oxford comma:
Suggested change
| Build and host Agents on Cloudflare, connect chat, voice, email, Slack, and webhooks to a durable agent runtime with Browser, Sandbox, AI Search, MCP, Payments and other MCP tools. | |
| Build and host Agents on Cloudflare, connect chat, voice, email, Slack, and webhooks to a durable agent runtime with Browser, Sandbox, AI Search, MCP, Payments, and other MCP tools. |
| @@ -0,0 +1,74 @@ | |||
| --- | |||
| title: Harnesses | |||
Contributor
There was a problem hiding this comment.
Add a description (required for all pages with pcx_content_type):
Suggested change
| title: Harnesses | |
| title: Harnesses | |
| description: Understand agent harnesses — the loop that controls planning, tool use, and response flow. |
Contributor
|
Posted a review on PR #31098. Findings:
I posted inline suggestions for the harnesses description and the Oxford comma. The missing |
Contributor
|
CI run failed: build logs |
Contributor
Broken LinksFound 33 broken link(s) across 20 file(s).
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
11 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
[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:
src/components/AgentsPlatformDiagram.astrosrc/content/docs/agents/harnesses/index.mdxsrc/content/docs/agents/communication-channels/email.mdxsrc/content/docs/agents/communication-channels/slack.mdxsrc/content/docs/agents/tools/sandbox.mdxsrc/content/docs/agents/tools/mcp.mdxsrc/content/docs/agents/tools/browser.mdxDeleted 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 byconcepts/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:
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/*, andmodel-context-protocol/*guides/*→examples/*,communication-channels/*,runtime/*, andmodel-context-protocol/*agentic-payments/*→tools/payments/*model-context-protocol/*stays asmodel-context-protocol/*platform/limits.mdxstays asplatform/limits.mdxguides/chatgpt-app.mdxmoved toworkers/demos/chatgpt-app.mdxconcepts/human-in-the-loop.mdx→ Moved underconcepts/agentic-patterns/.concepts/workflows.mdx→ Merged intoruntime/execution/run-workflows/.GitHub should show most of these as renames. The content was intentionally kept close to the original to avoid review noise.
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