docs(website): add an agent runtimes docs section - #913
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
blove
enabled auto-merge (squash)
September 1, 2026 02:50
One `runtimes` docs library with a section per measured AG-UI runtime — AWS Strands, Microsoft Agent Framework, and Mastra — each carrying an overview, a local quickstart, and a page recording the wire conventions measured on 2026-08-31. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The Mastra Railway service and AG_UI_MASTRA_URL are now provisioned, and POST examples.threadplane.ai/runtimes/mastra/agent returns a real RUN_STARTED -> TEXT_MESSAGE_CHUNK -> RUN_FINISHED stream. Drop the hosted-backend caveat and the local-quickstart-as-workaround framing, and match the See-it-live callout the Strands and MAF overviews use. Also correct the now-false 'not yet running in the hosted demo deployment' note on the runtime matrix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
blove
force-pushed
the
blove/docs-runtimes-section
branch
from
September 1, 2026 02:52
177799e to
fbe43ee
Compare
Contributor
This was referenced Sep 1, 2026
blove
added a commit
that referenced
this pull request
Sep 1, 2026
…untimes The cockpit -> docs direction shipped with both libraries (COCKPIT_DOCS_LINKS covers all six deep-agents entries and all four runtimes entries), but the reverse table only knew the five first-iteration pages. Every deep-agents page (#937) and every runtimes page (#913) sent its Run/Code/API buttons to Cockpit home instead of the demo the page describes. Add the 16 missing entries: - deep-agents: the five capability pages map to their core-capabilities topic; the introduction maps to deep-agents/getting-started/overview. - runtimes: all three pages of each runtime section (overview, quickstart, how-it-connects) map to that runtime's one demo, since a single demo serves them equally well; the introduction maps to runtimes/getting-started/overview. Also add deep-agents and runtimes to AnalyticsLibrary. Without it every handoff from these two libraries would have been attributed to 'unknown', so the new links would be invisible in the funnel they exist to feed. Each of the ten destination URLs was checked against production and returns a hard 200. The check discriminates: an unknown topic 307s to the fallback and an unknown product 500s, so the 200s are real pages rather than SPA soft-200s. Tests: the exact pin is updated, plus four guards — every key names a page that exists in docs-config (a typo'd key is otherwise invisible: the page just keeps the Cockpit-home fallback), the deep-agents/runtimes links round-trip against COCKPIT_DOCS_LINKS, the analytics library is no longer 'unknown', and each runtime section's three pages resolve to the same demo. All four were mutation-tested to confirm they fail when the mapping is wrong. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
blove
added a commit
that referenced
this pull request
Sep 1, 2026
…untimes The cockpit -> docs direction shipped with both libraries (COCKPIT_DOCS_LINKS covers all six deep-agents entries and all four runtimes entries), but the reverse table only knew the five first-iteration pages. Every deep-agents page (#937) and every runtimes page (#913) sent its Run/Code/API buttons to Cockpit home instead of the demo the page describes. Add the 16 missing entries: - deep-agents: the five capability pages map to their core-capabilities topic; the introduction maps to deep-agents/getting-started/overview. - runtimes: all three pages of each runtime section (overview, quickstart, how-it-connects) map to that runtime's one demo, since a single demo serves them equally well; the introduction maps to runtimes/getting-started/overview. Also add deep-agents and runtimes to AnalyticsLibrary. Without it every handoff from these two libraries would have been attributed to 'unknown', so the new links would be invisible in the funnel they exist to feed. Each of the ten destination URLs was checked against production and returns a hard 200. The check discriminates: an unknown topic 307s to the fallback and an unknown product 500s, so the 200s are real pages rather than SPA soft-200s. Tests: the exact pin is updated, plus four guards — every key names a page that exists in docs-config (a typo'd key is otherwise invisible: the page just keeps the Cockpit-home fallback), the deep-agents/runtimes links round-trip against COCKPIT_DOCS_LINKS, the analytics library is no longer 'unknown', and each runtime section's three pages resolve to the same demo. All four were mutation-tested to confirm they fail when the mapping is wrong. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
blove
added a commit
that referenced
this pull request
Sep 1, 2026
…untimes The cockpit -> docs direction shipped with both libraries (COCKPIT_DOCS_LINKS covers all six deep-agents entries and all four runtimes entries), but the reverse table only knew the five first-iteration pages. Every deep-agents page (#937) and every runtimes page (#913) sent its Run/Code/API buttons to Cockpit home instead of the demo the page describes. Add the 16 missing entries: - deep-agents: the five capability pages map to their core-capabilities topic; the introduction maps to deep-agents/getting-started/overview. - runtimes: all three pages of each runtime section (overview, quickstart, how-it-connects) map to that runtime's one demo, since a single demo serves them equally well; the introduction maps to runtimes/getting-started/overview. Also add deep-agents and runtimes to AnalyticsLibrary. Without it every handoff from these two libraries would have been attributed to 'unknown', so the new links would be invisible in the funnel they exist to feed. Each of the ten destination URLs was checked against production and returns a hard 200. The check discriminates: an unknown topic 307s to the fallback and an unknown product 500s, so the 200s are real pages rather than SPA soft-200s. Tests: the exact pin is updated, plus four guards — every key names a page that exists in docs-config (a typo'd key is otherwise invisible: the page just keeps the Cockpit-home fallback), the deep-agents/runtimes links round-trip against COCKPIT_DOCS_LINKS, the analytics library is no longer 'unknown', and each runtime section's three pages resolve to the same demo. All four were mutation-tested to confirm they fail when the mapping is wrong. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
blove
added a commit
that referenced
this pull request
Sep 1, 2026
…untimes (#938) The cockpit -> docs direction shipped with both libraries (COCKPIT_DOCS_LINKS covers all six deep-agents entries and all four runtimes entries), but the reverse table only knew the five first-iteration pages. Every deep-agents page (#937) and every runtimes page (#913) sent its Run/Code/API buttons to Cockpit home instead of the demo the page describes. Add the 16 missing entries: - deep-agents: the five capability pages map to their core-capabilities topic; the introduction maps to deep-agents/getting-started/overview. - runtimes: all three pages of each runtime section (overview, quickstart, how-it-connects) map to that runtime's one demo, since a single demo serves them equally well; the introduction maps to runtimes/getting-started/overview. Also add deep-agents and runtimes to AnalyticsLibrary. Without it every handoff from these two libraries would have been attributed to 'unknown', so the new links would be invisible in the funnel they exist to feed. Each of the ten destination URLs was checked against production and returns a hard 200. The check discriminates: an unknown topic 307s to the fallback and an unknown product 500s, so the 200s are real pages rather than SPA soft-200s. Tests: the exact pin is updated, plus four guards — every key names a page that exists in docs-config (a typo'd key is otherwise invisible: the page just keeps the Cockpit-home fallback), the deep-agents/runtimes links round-trip against COCKPIT_DOCS_LINKS, the analytics library is no longer 'unknown', and each runtime section's three pages resolve to the same demo. All four were mutation-tested to confirm they fail when the mapping is wrong. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
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
1 participant
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.
Adds a
runtimesdocs library to the website, one section per measured AG-UI runtime.apps/website/content/docs/had no runtimes content at all, so nothing on the site described the three examples undercockpit/runtimes/.Structural assumption (flip this if you disagree)
One
runtimeslibrary with a section per runtime, mirroring howapps/website/src/lib/docs-config.tsstructures the existing libraries:A
getting-started/introductionpage is not optional here:libraryIntroPath()is what the breadcrumb and the BreadcrumbList structured data both point at for every library.The alternative — three separate top-level libraries — would triple the sidebar entries in the docs nav for what is really one comparison.
Finding:
docsPathdoes not resolve anywhere, for any productThe runtimes descriptors declare
docsPath: '/docs/runtimes/core-capabilities/<topic>/overview/<lang>'. Before writing anything I checked where the existing products'docsPathvalues resolve in production. They do not:threadplane.ai/docs/langgraph/core-capabilities/streaming/overview/pythonexamples.threadplane.ai/docs/langgraph/core-capabilities/streaming/overview/pythonexamples.threadplane.ai/langgraph/core-capabilities/streaming/overview/pythonthreadplane.ai/docs/langgraph/guides/streaming(the real website route)The website serves a three-segment docs route,
/docs/[library]/[section]/[slug]. EverydocsPathin the repo is five segments. Grepping the consumers,docsPathis declared inlibs/cockpit-shell/src/lib/capability-contract.ts, copied throughapps/cockpit/src/lib/route-resolution.tsintoCapabilityPresentation, and then rendered as a link nowhere. It is dead metadata under a repo-wide convention that no route serves, andcockpit/*/matrix.spec.tsasserts its exact shape.So the runtimes
docsPathvalues are not specially broken — they are consistent with every other product. This PR therefore leaves all descriptors untouched, which also means no generator artifacts and no drift-check surface. Pointing only the runtimes descriptors at the new website URLs would have made runtimes the one product that breaks the convention, for a link that still is not rendered.Wiring
docsPathto a real destination is a separate change and worth doing — it needs a decision about whether the cockpit deep-links into the website or a five-segment route is added. Happy to take that next.Content
Source of truth was the measured matrix in
content/docs/choosing-an-adapter/index.mdx,docs/superpowers/plans/2026-08-31-runtime-portability-matrix.md, the twocockpit/runtimes/*/python/docs/guide.mdguides, and — for Mastra, which has no guide —deployments/ag-ui-mastra/README.mdplusagents.mjs.runtimes/getting-started/introductionruntimes/aws-strands/overviewruntimes/aws-strands/quickstartruntimes/aws-strands/how-it-connectsruntimes/microsoft-agent-framework/overviewruntimes/microsoft-agent-framework/quickstartruntimes/microsoft-agent-framework/how-it-connectsruntimes/mastra/overviewruntimes/mastra/quickstartruntimes/mastra/how-it-connectsPer-runtime honesty is kept rather than smoothed: Strands state is documented as snapshot-only and opt-in per
ToolBehaviorhook, with the full-object requirement called out; subagents are red on all three with the three different upstream reasons named; the staleag-ui-strandsPyPI wheel and the git pin are explained.Mastra is thinner than the others, but its hosted demo is live
Mastra has no
docs/guide.md, so its three pages are assembled from the deployment README, the agent source, and the matrix. I did not pad the gap — those pages carry less first-party prose than the Strands and MAF ones by design.An earlier revision of this PR warned that the hosted Mastra demo had no reachable backend. That was accurate when measured (
AG_UI_MASTRA_URLwas unset and the proxy returned500 no upstream configured for topic mastra) and is no longer true: the Railway service, volume, domain, and Vercel env var have since been provisioned. Re-verified directly against production before rewriting:A real model call end to end. Commit
177799ebtherefore drops the caveat, gives the Mastra overview the same See it live callout the Strands and MAF overviews use, and keeps the local Quickstart as ordinary run-it-yourself content rather than a workaround.It also corrects
content/docs/choosing-an-adapter/index.mdx, which still said the Mastra row was "not yet running in the hosted demo deployment". That page is the source of truth these new pages cross-link, so leaving it contradicting them was not an option. The genuinely durable distinction is kept: Mastra is not served by the shared FastAPI deployment, because upstream ships no plain AG-UI HTTP endpoint.Also changed
LibraryMarkgains alayersglyph for the new library (MARKSisRecord<LibraryId, …>, so it is exhaustive)./docsindex gains one helper link under "Pick your backend": Running a non-LangGraph backend? Agent runtimes →.Verification
npx vitest run --config vite.config.mtsinapps/website: 390 passed, 48 files, 0 failed — re-run green after commit177799eb. Includes the configured-page sweep, the no-orphan-MDX sweep, description uniqueness, the ≤160-char clamp, sitemap coverage, internal-link validity, and the docs structured-data suite.sitemap-dates.spec.tsfailed while the new MDX files were untracked, because it dates routes from git history. Committing them fixed it. Anyone adding docs pages will hit this.npx next build: clean, docs route now prerenders 121 paths (was 111).npx nx lint website: 0 errors (31 pre-existing warnings)./docs/choosing-an-adapterafter commit177799eb.Not auto-merged.
🤖 Generated with Claude Code