Closes#6607.
Verified against the pinned `langgraph_prebuilt` (1.1.0):
`create_react_agent` has neither `middleware` nor `system_prompt`
parameters, rejects `state_schema=CopilotKitState`, and is deprecated in
favour of `langchain.agents.create_agent`. Readers following the comment
hit an immediate `TypeError`.
All 7 occurrences on `main` are updated (4 sites noted in the issue plus
the 3 that landed with #5469):
-
`showcase/shell-docs/src/content/docs/integrations/langgraph/agent-app-context.mdx`
(Python + TypeScript)
-
`showcase/shell-docs/src/content/docs/integrations/langgraph/frontend-tools.mdx`
(Python + TypeScript)
-
`showcase/shell-docs/src/content/snippets/integrations/langgraph/frontend-tools.mdx`
(Python + TypeScript)
- `showcase/shell-docs/src/content/reference/hooks/useFrontendTool.mdx`
(Python)
Each comment is replaced with an accurate note (”`create_agent`
supersedes the deprecated `create_react_agent`, which accepts neither
`middleware=` nor `system_prompt=`”), and the TypeScript snippets now
reference `createReactAgent` (camelCase) instead of the Python
`create_react_agent` name — the second, smaller problem noted in the
issue.
Open Inspector Event Snippets on localhost. You can compile, save, and
replay AG-UI events in chat. Chat shows a bookmark icon next to a tool
call, an A2UI block, or generative UI. Click the icon to save that turn
as a snippet.
## What does this PR do?
This PR adds the Inspector Event Snippets pane.
You can:
- Compile a snippet from a recipe (tool-call, reasoning, text, activity,
raw)
- Save snippets in origin-scoped localStorage
(`cpk:inspector:event-snippets`)
- Import and export snippets from the pane header
- Replay a snippet into live chat through Inspector-only Core inject
Each Run remints `messageId`, `parentMessageId`, `toolCallId`, and
`runId`. The second Run of the same snippet is a new turn.
On localhost, chat shows a bookmark icon beside a tool call, A2UI block,
or generative UI. The icon is absolutely positioned. It hangs to the
right when there is room. Otherwise it hangs to the left. The card stays
full chat width.
The React demo adds `sayHello`, `getTime`, `addNumbers`, and a **Call 3
tools** suggestion.
## Related PRs and Issues
- Linear
[OSS-874](https://linear.app/copilotkit/issue/OSS-874/new-features-also-allow-users-to-emit-specific-events-from-the)
## Checklist
- [x] I have read the [Contribution
Guide](https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md)
- [x] If the PR changes or adds functionality, I have updated the
relevant documentation
- [x] "Allow edits by maintainers" is checked (lets us help iterate on
your PR directly — faster turnaround for everyone)
## Testing
### Commands run
1. Lefthook pre-commit ran `nx` targets `test`, `publint`, and `attw`
for 27 affected projects. All passed.
2. I did not run `pnpm test:pr` (full repo). Lefthook ran the affected
package matrix only.
### Manual test
1. Run `pnpm demo:react` from the repo root.
2. Open http://localhost:3000
3. Open Inspector and select Event Snippets.
4. In chat, click **Call 3 tools**. Confirm three tool cards at full
chat width, with the bookmark hanging outside the card.
5. Click a bookmark, then click Run twice. Chat shows a second turn with
new IDs.
### How this PR makes testing easy
- `packages/web-inspector/src/lib/__tests__/event-snippets.test.ts`
- `packages/core/src/__tests__/inspect-inject.test.ts` (covers two
injects)
- React demo: `examples/v2/react/demo/src/app/page.tsx`
## Linked issues
Linear
[OSS-874](https://linear.app/copilotkit/issue/OSS-874/new-features-also-allow-users-to-emit-specific-events-from-the)
## Risk / rollback
- If ID remint is wrong, a second Run can no-op or duplicate a turn.
- The save icon shows on localhost Inspector (or when `showDevConsole`
is `true`).
- Rollback: revert this PR.
## Public API change
**Before**
Angular has no Inspector service.
```ts
// no CopilotInspector export from @copilotkit/angular
```
**After**
```ts
import { CopilotInspector } from "@copilotkit/angular";
const inspector = inject(CopilotInspector);
inspector.openInspector({
messageId: "msg-1",
menu: "event-snippets",
});
```
React and Vue apps that already mount Inspector on localhost need no new
caller code. Chat wires the bookmark through Inspector context.
`@copilotkit/core` exports `ɵinjectInspectorEvents` for Inspector only.
App code must not call it. There is no public Core emit API.
Every framework quickstart sets runtimeUrl="/api/copilotkit". That resolves
only because Next.js serves the app and the runtime from one origin, and
nothing on the page said so -- so a reader on a client-only frontend followed
a step that could not work for them.
Annotate the provider step in all 13 quickstarts that carry it, pointing at
the per-frontend guides that show a standalone runtime server and an absolute
runtimeUrl.
The callout deliberately uses no root-relative links. The Angular surface
reuses these same integration quickstarts via resolveAngularDoc's fallback to
frameworkContentSlug, and its link contract keeps readers inside /angular/**;
linking three other frontends' pages both broke that contract and was wrong
content for an Angular reader.
aws-strands is left un-annotated while the Strands rejuvenation is underway.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A React single-page app is the one frontend the docs could not get to a
working runtime. Every framework quickstart hosts the runtime in a Next.js
route handler and uses a relative runtimeUrl of /api/copilotkit, which only
resolves because Next.js serves the app and the runtime from one origin. A
Vite or CRA app has neither a server nor a shared origin, so that step had
nowhere to land.
Add a React SPA page covering only that difference: a standalone Node runtime
server, the absolute runtimeUrl it requires, and cors: true -- which is off by
default on createCopilotNodeListener, unlike the Express and Hono adapters.
Everything else links back to the root React docs rather than restating them.
Registering react-spa in the frontend registry is what makes /react-spa
resolve; route resolution is gated on isFrontendId, so an unregistered page
404s. Vue and React Native are the precedent: registered, single-page, no
namespaced subtree. The existing registry-driven guard in frontend-options
already covers the new page.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
## What does this PR do?
Twelve integration quickstarts opened by telling the reader to create a
free account and get a license key, then — seven steps later — showed a
runtime constructed like this:
```ts
const runtime = new CopilotRuntime({
agents: { ... },
runner: new InMemoryAgentRunner(),
});
```
`runner` and `intelligence` are mutually exclusive by construction
(`CopilotSseRuntimeOptions` declares `intelligence?: undefined`), so the
key provisioned in step 1 could not be consumed. Threads read "locked",
and nothing on the page indicated a choice had been made. Worse, **none
of the twelve pages ever named `INTELLIGENCE_API_KEY`** — after step 1
the key was never mentioned again.
Each page now:
1. Constructs the runtime with `intelligence: new
CopilotKitIntelligence({ apiKey: process.env.INTELLIGENCE_API_KEY! })`
and `identifyUser`.
2. Names `INTELLIGENCE_API_KEY` in a `.env.local` fence at the point the
route reads it.
3. Links `/premium/connect-your-runtime` — a good page that had **zero**
inbound links from any quickstart — from a callout that also documents
the in-memory opt-out.
The in-memory runner stays available and is labelled as the opt-out. It
was already the default (`super(options, options.runner ?? new
InMemoryAgentRunner())`), so passing it explicitly only ever added the
steer.
Also adds the required `name` field to the `identifyUser` snippets in
`connect-your-runtime.mdx` and the runtime skill's `agent-runners.md`.
Both omitted it, so copying either was a type error:
```
Property 'name' is missing in type '{ id: string; }' but required in type 'CopilotRuntimeUser'
```
### Scope
Not "every page mentioning `InMemoryAgentRunner`" — that is 37 files,
and most are legitimate (`backend/agent-runner.mdx` is *about* runners;
an AgentCore host is a Lambda and cannot host the Intelligence socket at
all). The scope is **pages that provision a license key and then show a
runtime that cannot consume it**, which partitions those 37 cleanly into
12 in-scope and 25 untouched.
Note that includes `docs/agent-spec/quickstart.mdx`, which is
byte-identical to `docs/integrations/agent-spec/quickstart.mdx`. Both
are fixed here; retiring the duplication is filed separately.
## Verification
Nine of the twelve runtime fences are `doctest="component"` gated, so
they are really compiled in CI against a pinned
`@copilotkit/runtime@1.68.3`. The new constructor was proven there
before being applied to twelve files.
- Extracted the docs tree with `scripts/doc-tests/extract.ts` → 16
snippets. **All 15 `component` snippets typecheck clean**, covering 9 of
the 12 edited pages plus 6 untouched pages (so it also rules out
collateral damage).
- Confirmed the gate can go red: removing `name` from an edited snippet
reproduces exactly the error above, so the pass above is meaningful.
- The 3 ungated fences (mastra ×1, langgraph ×2) were typechecked by
hand, since CI will not.
- `src/lib/__tests__/intelligence-wiring-docs.test.ts` passes 3/3. That
suite guards this defect class, and **this change brings these pages
into its coverage for the first time — 8 → 20 pages**, because a page
only enters the suite once it actually configures `intelligence`.
- `pnpm check:intelligence-env-names` passes. `pnpm check:plugin-skills`
initially failed (`packages/runtime/skills/**` is mirrored to
`skills/**`); synced, both copies included.
## Related PRs and Issues
- Closes OSS-932
- Part of the OSS-923 split, alongside OSS-933 (runtime silently drops
`runner` alongside `intelligence`)
- OSS-935 — the byte-identical agent-spec duplication
- OSS-936 — the Mastra fence's `getLocalAgents({ mastra })` does not
compile against `@ag-ui/mastra@1.1.2`. **Pre-existing on
`origin/main`**, reproduced on the unmodified snippet, not addressed
here
Worth noting for reviewers: the Mastra runtime fence cannot be
doctest-gated as written (it imports the `@/mastra` path alias, which
does not resolve in the extracted directory), and `@ag-ui/mastra` is in
no `doctest.json`. It is the least-verified page in the set on two
independent axes, and it accumulated two unrelated defects. That may
explain why only the Mastra evaluation cell surfaced this.
## Checklist
- [x] I have read the Contribution Guide
- [x] If the PR changes or adds functionality, I have updated the
relevant documentation
- [x] "Allow edits by maintainers" is checked
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Resolves conflicts in the two custom-agent docs copies. Main's "docs: update
Anthropic model references to Opus 4.8" (518feae6cd) independently bumped the
Anthropic thinking snippets to `claude-sonnet-4-6` -- the same model id this
branch picked -- so the overlap was textual, not a disagreement.
Kept this branch's side in both files: it already carries that model id and
additionally moves the AI SDK options into `providerOptions.anthropic` and
switches to `{ type: "adaptive" }` with `effort`. Main's bumps on the
surrounding property-forwarding examples merge in unchanged.
Twelve quickstarts provisioned a license key in step 1 and then showed a
runtime constructed with `runner: new InMemoryAgentRunner()` — an option
that is mutually exclusive with `intelligence`, so the key was never read.
Threads showed "locked" and nothing indicated a choice had been made.
Each of those pages now constructs the runtime with `intelligence` and
`identifyUser`, names `INTELLIGENCE_API_KEY` where the route reads it, and
links /premium/connect-your-runtime — which had no inbound link from any
quickstart. The in-memory runner stays available as a labelled opt-out;
it was already the default, so passing it explicitly only added the steer.
Also adds the required `name` field to the `identifyUser` snippets in
connect-your-runtime.mdx and the runtime skill's agent-runners reference.
Both omitted it, so copying either was a type error.
Scope is every page that provisions a key and then shows a runtime that
cannot consume it. Pages that legitimately document the in-memory runner
(backend/agent-runner, deploy/agentcore) are unchanged.
Verified: all 15 doctest `component` snippets typecheck against the pinned
@copilotkit/runtime@1.68.3, and the gate goes red when `name` is removed.
Add chat phrases and lab buttons that fail a frontend tool or emit RUN_ERROR.
Clear the Break threads cookie on load so a refresh does not keep a fake
thread-list failure.
Self-review of the previous commit found three defects, two of them factual
errors I asserted without checking.
1. The promise form can kill the process. I documented
`agents: MastraAgent.getRemoteAgents({ ... })` and described its failure mode
as "the rejection is cached and every later request fails". That understated
it: the call starts at module load with nothing awaiting it, so an agent
server that is not up yet produces an *unhandled* rejection and Node
terminates. Both files now lead with the factory form, which has no such
window — nothing runs until a request arrives, a failure is a 500, and the
next request retries.
2. The tsconfig warning named the wrong key. `next dev` does not overwrite
`moduleResolution: "NodeNext"` — `nodenext` is in Next's accepted set for
both `module` and `moduleResolution`. What it actually does at its own root
is force `esModuleInterop`, `isolatedModules`, `resolveJsonModule` and `jsx`,
set `noEmit: true`, and replace `include`/`exclude`. `noEmit` is the sharp
one for an agent project that compiles with `tsc`. The advice stands; the
mechanism is now the verified one.
3. `MASTRA_BASE_URL` was set in the wrong shell. It was exported in the agent's
terminal, where the frontend cannot see it. It now appears as `.env.local` in
the Next app, next to the route that reads it. The port note moved to the
step that starts the agent, and says what `mastra dev` really does: 4111 when
free, walking up to 4131 when not.
Verified:
shipped fence, agent down -> up -> 500, then 200; process survived, no restart
promise form, agent down -> node terminated on unhandled rejection
next build, NodeNext tsconfig -> 13 keys written; module/moduleResolution untouched
mastra CLI -> serverPort 4111, getPort over 4111..4131, apiPrefix /api
extracted fence, runner config -> tsc exit 0; mutation (drop resourceId) -> TS2741
MDX compile, both files -> OK
The behavioural checks drove the extracted fence itself, not a paraphrase of it.
Refs OSS-925.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`MastraAgent.getRemoteAgents` appeared nowhere in this repo — not in
shell-docs, not in an example. The only wiring the Mastra quickstart taught was
`getLocalAgents({ mastra })` behind `import { mastra } from "@/mastra"`,
including on the "Use an existing agent" branch, which two steps earlier tells
you to `create-next-app` a *separate* directory. That import cannot resolve, and
the shape it teaches moves a running Mastra service into the frontend, deleting
the process the reader was trying to keep.
All four cells of the 2026-08-21 Mastra x Next.js sweep reached the agent over
HTTP, and all four derived how on their own; `both` filed it as its largest
friction and `empty` as its worst papercut at ~10 minutes.
- Quickstart, existing-agent branch: wire the route with `getRemoteAgents` over
a `MastraClient`, add the `MASTRA_BASE_URL` convention, and add the missing
step that starts the agent server. `/api/agents` is the liveness check; a
bare `GET /` answers 200 from Mastra's console whether an agent is registered
or not.
- Warn that `next dev` rewrites the `tsconfig.json` at its own root, so the
frontend belongs in a sibling package — the reason this path goes over HTTP.
- copilot-runtime.mdx: a "Local vs remote agents" section that decides between
them by where the agent runs, with the full `GetRemoteAgentsOptions` contract,
the promise-vs-factory trade-off, and the local-only options
(`requestContext`, `untilIdle`).
- Gate the new route fence in CI (`doctest="component"` plus a mastra
`doctest.json`). The old fence could never have been gated: `@/mastra` does
not resolve. Mastra now has its first typechecked route snippet.
Verified:
MDX compile, both files -> OK (mutation-checked: unclosed tag -> FAIL)
doc-test extraction -> 21 -> 22 fences; mastra sidecar selected
extracted fence, runner config -> tsc exit 0 (runtime 1.68.3; ag-ui/mastra 1.1.1, 1.1.2)
mutation: drop resourceId -> tsc exit 1, TS2741
previously documented shape -> tsc exit 2, resourceId missing
validate-intelligence-env-names -> exit 0
Not run: the shell-docs vitest suite. No test reads either file and no page was
added or moved, so nav, sitemap and llms.txt are unchanged.
Refs OSS-925.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Closes OSS-901.
## Problem
`/mastra/generative-ui/a2ui/fixed-schema` could not be followed. A
Mastra onboarding run on Codex stopped there rather than invent an API,
reporting that the guide "depends on unbundled showcase helpers."
That is true, and the mechanism is worse than the report. Region bodies
are assembled at bundle time, so what ships is invisible in a source
diff. The `backend-render-operations` marker sits on **line 1** of
`mastra/src/mastra/tools/index.ts` — put there by the marker-hoist sweep
in 34b6418 so snippets would carry their imports — and the closing
marker is at the bottom of the file. The page therefore published **all
432 lines** of the tools barrel: weather, stock price, dice, d20,
query-data, schedule-meeting, search-flights, the aimock
header-forwarding import, and
```ts
import { generateA2uiImpl, buildA2uiOperationsFromToolCall } from "@copilotkit/showcase-shared-tools";
```
`@copilotkit/showcase-shared-tools` is not a package. It is a tsconfig
`paths` entry (`mastra/tsconfig.json:23`) pointing at `./shared-tools`,
a symlink to `showcase/shared/typescript/tools`. There is nothing for a
reader to install.
Same defect on the strands page from the same sweep: 586 lines of a
1688-line `agents/agent.py`.
## What changed
**The two cells get a dedicated module for the A2UI tool**, so hoisting
the marker to the top of the file yields exactly the tool plus its own
imports. This is the shape of the reference cell
(`langgraph-typescript/src/agent/a2ui-fixed.ts`, which likewise builds
A2UI operations locally) and, on the Python side, of `gen_ui_agent.py` /
`a2ui_dynamic.py`.
| page | before | after |
| --- | --- | --- |
| mastra fixed-schema | 432 lines, 16.5 KB | 166 lines |
| strands fixed-schema | 586 lines | 171 lines |
Every line in the new snippets either installs from npm or is a visibly
local `./` / `@/` module carrying a comment about what a real app uses
instead. Mastra keeps a single operation builder — the beautiful-chat
flight tool now calls the same one. The strands cell also highlights
`tools/generate_a2ui.py` so the guide shows the helper the tool calls.
**A guard in the bundler**, because neither failure mode shows up in
review:
- any `@copilotkit/showcase-*` specifier in a published body fails the
build (corpus is at zero after this change, so no baseline);
- over 200 lines fails the build (median region is 28, p90 is 125; the
48 already over the line are baselined by `slug::region::file` and the
list only shrinks).
**The entrypoint half of the issue lands differently than I first read
it.** OSS-901 flagged `@copilotkit/runtime` +
`@copilotkit/react-core/v2` on the shared A2UI page as a v1/v2 trap. It
is not a broken pairing — v1's `CopilotRuntime` forwards `a2ui` (and
`mcpApps` / `openGenerativeUI`) straight to the v2 runtime
(`packages/runtime/src/lib/runtime/copilot-runtime.ts:414`). But #6618
landed while this branch was open and retired the v1 runtime adapter
across every showcase integration, so the page's v1 root import *was*
the stale half. The block also imported `ExperimentalEmptyAdapter` and
`copilotRuntimeNextJSAppRouterEndpoint` and used neither, so it was a
route a reader could not run. It now shows `createCopilotRuntimeHandler`
from `@copilotkit/runtime/v2` in the single-route form, matching the
rebased showcase route and `/runtime-server-adapter`, with a note that
the legacy form still works.
**On the systemic question.** A separate sweep counted ~50 regions whose
marker sits on line 1 with a matching close at end-of-file, and proposed
failing a region that spans >=90% of its file. That rule does not
survive contact with the published bodies: of 141 regions at >=90% span,
only **2** publish more than 200 lines, and 98 publish under 100 —
dedicated single-purpose files whose whole content *is* the intended
snippet. It would also flag this PR's own fix
(`strands/a2ui_generate.py` is 171/188 = 91%) and the langgraph
reference cells. Published size is the signal that separates the defect
from the pattern, which is what the guard here measures.
## Testing
**Guard catches the pre-fix tree** (restored HEAD sources, moved the new
modules aside, ran the bundler):
```
REAL EXIT=1
Region bodies importing repo-only modules:
mastra::agentic-chat: region "weather-tool-backend" (src/mastra/tools/index.ts) imports "@copilotkit/showcase-shared-tools", ...
mastra::agentic-chat: region "backend-render-operations" (src/mastra/tools/index.ts) imports "@copilotkit/showcase-shared-tools", ...
Region bodies over the published-snippet limit:
strands::a2ui-fixed-schema: region "backend-render-operations" (src/agents/agent.py) publishes 586 lines (limit 200) ...
```
and passes on this branch (`bundler exit=0`, 801 demos bundled).
**Guard unit tests** —
`showcase/scripts/lib/__tests__/demo-region-guard.test.ts`, 10 passed.
Mutation-checked: raising `MAX_REGION_LINES` and short-circuiting the
alias scan fails exactly 2 of them; restoring passes 10/10.
**Showcase script suites** — `demo-region-guard`, `bundle-demo-content`,
`validate-parity`, `verify-shell-docs`, `validate-shared-symlinks`:
**151 passed (5 files)**.
**Mastra vitest** — `tests/vitest/a2ui-context.test.ts`, 5 passed. The
prompt builder lives in the dependency-free `a2ui-context.ts` so this
regression test still runs without the Mastra SDK installed, as it did
before. Mutation-checked: breaking the join fails 1 of 5.
**Strands pytest** — `tests/python/test_generate_a2ui_errors.py` 11
passed (was 1 failed / 10 passed after the move, because the happy-path
test patched `agents.agent.build_a2ui_operations_from_tool_call`;
retargeted at the new module). Whole runnable suite: **40 passed**
across `test_generate_a2ui_errors`, `test_hook_injection`,
`test_sales_state_from_args`, `test_tool_call_cap`. Mutation-checked:
stubbing out the builder call fails the happy-path test.
`test_cvdiag_boundaries` / `test_instrumentor_patch` need `starlette` /
`opentelemetry-instrumentation-threading`, absent from this venv —
unrelated to this change.
**Published snippet, rendered** (`demo-content.json` after bundling):
```
mastra snippet lines: 166 | file: src/mastra/tools/a2ui-generate.ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { generateText, tool as aiTool } from "ai";
// In your own app this is `import { openai } from "@ai-sdk/openai"`. ...
```
**Docs verification** — `verify-shell-docs.ts` produces a byte-identical
finding set with my two MDX edits toggled on and off (empty diff), so
the edits add no new findings. `component-imports`, `essential-content`
and the rest are unchanged; the suite's pre-existing failures are
untouched.
**Lint / format** — `oxfmt` on all changed TS, `oxlint` clean on the new
and edited files.
## Follow-ups (not in this PR)
- The 48 baselined regions are the same class of defect on other pages —
`strands::supervisor-delegation-tools` publishes 795 lines,
`strands::subagent-setup` 625, `ms-agent-dotnet::weather-tool-backend`
549. Each wants the same split.
- `claude-sdk-typescript/shared-tools/` and
`langgraph-typescript/shared-tools/` are real directories where symlinks
belong — the erosion `showcase/AGENTS.md` documents. Untouched here.
- Dropping the strands commit (`14c7351`) is safe on its own; it only
requires adding
`strands::backend-render-operations::src/agents/agent.py` to the guard
baseline.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Two things this PR was missing, both now closed.
## The Claude SDK quickstarts are unblocked
#6618 put `showcase/integrations/claude-sdk-{python,typescript}` on
`createCopilotRuntimeHandler` with `mode: "single-route"`, at the **plain**
`route.ts` path. That dissolves the coupling that forced these two pages to be
reverted earlier: `verify-shell-docs.ts` asserts each page claims a starter file
at `src/app/api/copilotkit/route.ts` AND that the file exists in the extracted
starter. Single-route keeps that path, so the prose claims and
`requiredStarterFiles` are unchanged — only the fence bodies move to v2.
The two content assertions that pinned those pages to v1
(`ExperimentalEmptyAdapter`, `copilotRuntimeNextJSAppRouterEndpoint`) now
require `createCopilotRuntimeHandler`, the `/v2` entrypoint,
`mode: "single-route"` and a `POST` export. Mutation-checked: flipping the
fixture to `mode: "multi-route"` fails with
`app/api/copilotkit/route.ts missing single-route mode`.
## Snippet gating: 1 -> 20 route fences
I previously claimed the integration pages could not be doctested because of
path aliases and per-integration deps. **That was an assumption I never
checked, and it was wrong.** Of the 52 migrated route fences, 47 import nothing
project-relative; 36 are complete, self-standing routes. 27 pages were
eligible, 20 now hold a gated fence — each extracted and typechecked by
`tsc --noEmit` against real npm-installed packages in CI.
One fence per (page, title): `extract.ts` concatenates tagged blocks sharing a
title, so a second complete route on the same page would collide.
Mutation-checked on `snippets/integrations/langsmith/index.mdx`: restoring the
v1 import in the gated fence turns the run red (20 passed, 1 failed). My first
attempt at this check was a no-op — the pattern missed because the fence is
JSX-indented — and it "passed" misleadingly. The real check asserts the mutation
reached the extracted snippet before trusting the result.
### Harness changes this needed
- `extract.ts` now finds the nearest `doctest.json` by walking up to the docs
root, instead of looking only in the page's own directory. Otherwise gating
20 pages means ~20 duplicated dependency lists that then drift. A shared list
lives at `content/doctest.json`; `docs/integrations/langgraph/` keeps its own
(Python deps) and now also carries the TS deps its page needs.
- `run.ts` installs each dependency set **once**, into
`.doctest-output/.deps/<hash>`, and links it into every snippet sharing that
set. Per-snippet installs took **7:58** for 21 snippets, uncomfortably close
to the job's 15-minute timeout; shared installs take **0:45** cold. Different
dep sets still get separate stores, so this is a dedupe, not a merge.
### `@ag-ui/*` versions have to be pinned to what the runtime expects
Unpinned, the gated fences failed with `HttpAgent is not assignable to
AbstractAgent — separate declarations of a private property '_debug'`: npm
installs a newer `@ag-ui/client` than `@copilotkit/runtime` depends on, so two
`AbstractAgent` declarations collide. The sidecar pins `@ag-ui/client@0.0.57` and
`@ag-ui/core@0.0.57` to match `@copilotkit/runtime@1.68.3`.
## Seven fences are deliberately NOT gated
Un-tagged with the reason, rather than left failing or quietly dropped:
- `docs/auth.mdx`, `docs/premium/connect-your-runtime.mdx` — illustrative
fences referencing placeholders (`myAgent`, `verifyJwt`) that cannot compile
standalone by design.
- the four langgraph-family pages and
`snippets/self-hosting-copilot-runtime-langgraph-endpoint.mdx` — these hit
`LangGraphAgent is not assignable to AbstractAgent — separate declarations of
a private property '_debug'`, which pinning does not fix.
**That last one is a real pre-existing defect, not a migration regression.** I
reconstructed the v1 form of the langgraph quickstart snippet verbatim from
`origin/main` and typechecked it against the identical installed dependencies:
it fails with the same error. So these snippets have never typechecked against
published packages — worth filing separately. It is also what the ~220
`@ts-ignore` comments across `showcase/integrations` were papering over.
## Verified
doc-tests (cold, no cache) -> 21 passed, 0 failed in 0:45
mutation check (real, verified) -> 20 passed, 1 failed
vitest extract + verify-shell-docs -> 34 passed
showcase/shell-docs typecheck -> exit 0
showcase/shell-docs build -> exit 0
structural audit -> 21/21 pages, fence + JSX identical to HEAD
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Four docs pages configured a CopilotRuntime with an `intelligence` option that
nothing on the page produced. A Mastra onboarding run hit this on
/mastra/threads-lifecycle and stopped rather than invent a constructor
(OSS-900). The wiring itself was published as /premium/connect-your-runtime
under OSS-881; these pages were never connected to it.
- threads-lifecycle and headless-threads now build the client inline, so the
block a reader copies is complete
- headless-threads imported CopilotRuntime from the v1 root, whose runtime has
no `intelligence` option at all, and omitted the `identifyUser` that the
Intelligence runtime requires
- auth and backend/copilot-runtime keep their focused examples and gain a
pointer to the wiring page
The test enforces the contract page-scoped rather than per-fence, which is how
backend/runtime-endpoints already satisfies it.
The A2UI setup page imported `ExperimentalEmptyAdapter` and
`copilotRuntimeNextJSAppRouterEndpoint` and then used neither, so the block
was a truncated route a reader could not run. Show a complete route — and
show the current API while doing it: #6618 retired the v1 runtime adapter
across every showcase integration, so the page now uses
`createCopilotRuntimeHandler` from `@copilotkit/runtime/v2` in the
single-route form, matching `mastra/src/app/api/copilotkit-a2ui-fixed-schema/route.ts`
and the reference in /runtime-server-adapter.
That also settles the entrypoint question OSS-901 raised. The complaint was
that the page mixes v1 `@copilotkit/runtime` with `@copilotkit/react-core/v2`
below — not a broken pairing (v1's `CopilotRuntime` forwards `a2ui` straight
to the v2 runtime), but the v1 root import was the stale half, so both halves
of the page are now v2 entry points. The legacy form is noted as still
working for readers who are on it.
On the fixed-schema page, note that the LLM-driven integrations have no
`a2ui.render(...)` equivalent, so the operation builder in the snippet is
part of what a reader copies — and that the operations are nested, since a
flat `{ type: "create_surface" }` is silently ignored.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The earlier commits in this PR taught `createCopilotEndpoint` paired with
`handle` from `hono/vercel`, and added `hono` to 20 install commands with a
callout explaining why readers must install it. Both were wrong, and the second
was a consequence of the first.
`createCopilotEndpoint` is a **deprecated alias**. This repo's own handler table
says so — `docs/backend/runtime-endpoints.mdx`:
| Deprecated | Use instead |
| `createCopilotEndpoint` | `createCopilotHonoHandler` |
| `createCopilotEndpointSingleRoute` | ... with mode: "single-route" |
`createCopilotRuntimeHandler` serves the same multi-route mode (it is the
default), returns a plain fetch handler, is not deprecated, and needs **no hono
at all**. So the route collapses to:
const handler = createCopilotRuntimeHandler({
runtime,
basePath: "/api/copilotkit",
});
export const GET = handler;
export const POST = handler;
`hono` was therefore an artifact of the shape, not a requirement of the library.
The install lines and the callout are reverted; nothing tells readers to install
it any more.
## Verified with hono deleted, not merely absent from package.json
`examples/shadcn` converted to this shape, `hono` removed from its
`package.json`, and `node_modules/hono` deleted outright so a hoisted copy could
not mask the result:
GET /api/copilotkit/info -> 200
POST /api/copilotkit/agent/default/run -> 200, chat turn rendered
tsc --noEmit / eslint / next build -> clean
next build route -> ƒ /api/copilotkit/[[...slug]]
The doctest sidecar drops `hono` too, so the CI gate now typechecks the
canonical snippet against `@copilotkit/runtime` alone — proof by construction
that the snippet needs nothing else.
pnpm tsx scripts/doc-tests/run.ts -> 2 passed, 0 failed
showcase/shell-docs: typecheck -> exit 0
showcase/shell-docs: build -> exit 0
structural audit: 31/31 mdx files, fence + JSX identical to HEAD
## Also corrected
`docs/backend/custom-agent.mdx` repeated the same incorrect transport claim the
earlier commit fixed in four other places ("Both `<CopilotKit>` and
`<CopilotKitProvider>` negotiate the transport when the prop is omitted").
Corrected to match released behaviour.
## Left alone deliberately
`snippets/shared/backend/custom-agent.mdx` and `docs/backend/custom-agent.mdx`
still call `createCopilotEndpoint` in three fences each, as
`export default copilotEndpoint` — the Hono-app deployment pattern rather than a
Next.js route handler. That predates this PR, the documented replacement is
`createCopilotHonoHandler`, and I have not run that shape. Recorded as follow-up
rather than guessed at. (The two files have also drifted from each other, which
is a separate problem.)
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Seven fences already imported from `@copilotkit/runtime/v2` but were still
titled `app/api/copilotkit/route.ts`. That is the same title/body mismatch this
sweep exists to fix, seen from the other side: a reader follows the title,
creates a plain route file for a runtime that needs the catch-all path, and gets
no `/info`.
Titles only — no bodies changed.
Two categories are deliberately left on the plain path, because there it is
correct:
- fences mentioning `createCopilotEndpointSingleRoute`. Single-route mode is
served from a plain `route.ts` and is POST-only by design; retitling one would
destroy what it demonstrates.
- fences still on the v1 entrypoint. Those are separate migrations, blocked for
the reasons recorded in the PR description.
Verified:
pnpm tsx scripts/doc-tests/run.ts -> 2 passed, 0 failed
showcase/shell-docs: pnpm build -> exit 0
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Finishes the tractable remainder of the v1 -> v2 runtime sweep, and fixes a
docs claim that the previous commit's `useSingleEndpoint={false}` edits exposed
as wrong.
## The pairing guidance described unreleased behaviour
`backend/runtime-endpoints.mdx` is the authoritative page for provider/handler
pairs, and it said omitting `useSingleEndpoint` is safe on either provider
because the client negotiates from `/info` — with `auth.mdx` and two quickstart
callouts repeating it. That is true on `main` and false in every published
release: the compat `<CopilotKit>` wrapper still ships
useSingleEndpoint={props.useSingleEndpoint ?? true}
(verified in the published `@copilotkit/react-core` 1.68.3 bundle), so omitting
the prop selects the single-route transport and 404s against a multi-route
Runtime. The Runtime's own error body says so. `<CopilotKitProvider>` does
negotiate; only the wrapper pins — and every docs snippet uses the wrapper.
So the pairing table now splits the two providers instead of grouping them,
states that the pin exists in released versions and is removed on `main`, and
says plainly that passing `{false}` is the forward-compatible choice. The
"pinning the wrong mode 404s silently" warning now covers omitting the prop on
`<CopilotKit>`, which is the same failure by a different route. Same correction
applied to `auth.mdx` and to the two "Which provider goes with which handler?"
callouts, which additionally still named `copilotRuntimeNextJSAppRouterEndpoint`
as the route above them after that route became `createCopilotEndpoint`.
## Remaining migrations
- `self-hosting-remote-endpoints.mdx` — three LangGraph fragments moved to
`@copilotkit/runtime/v2` for `CopilotRuntime` and
`@copilotkit/runtime/langgraph` for the agents, splitting what was a single
v1 root import.
- `copilot-runtime.mdx` — the transport callout rewritten to match the
authoritative page and link to it, rather than asserting the default itself.
## Verified
pnpm tsx scripts/doc-tests/run.ts -> 2 passed, 0 failed
showcase/shell-docs: pnpm typecheck -> exit 0
showcase/shell-docs: pnpm build -> exit 0
structural audit: 6/6 mdx files, fence + JSX structure identical to HEAD
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Migrates the Next.js App Router runtime fences across the docs from the v1
entrypoint to the v2 multi-route shape proved in `examples/shadcn`: catch-all
path, `createCopilotEndpoint`, a runner, and both verbs exported. 38 fences
across 33 pages.
Only the boilerplate is rewritten. Each page's agent wiring — `MastraAgent`,
`LangGraphAgent`, `HttpAgent`, `BuiltInAgent`, middleware `.use(...)` calls —
is left byte-identical, because that part is not what was broken.
Three co-changes travel with every migrated page, since the shape does not work
without them:
- `hono` added to the page's install command (20 lines). It is a dependency of
`@copilotkit/runtime`, not a peer, so `hono/vercel` resolves under npm's flat
layout but not under pnpm.
- `useSingleEndpoint={false}` on `<CopilotKit>` (27 provider tags). The
provider defaults to the single-route transport, which posts to the bare
`runtimeUrl`; a multi-route runtime answers with 404. Only tags carrying a
`runtimeUrl` are touched — a provider using `agents__unsafe_dev_only` has no
runtime to match. Angular's `provideCopilotKit` defaults its transport to
`"auto"` and needs no equivalent, so those snippets are unchanged.
- fence titles retitled to the catch-all path, plus the prose that introduces
them, so no snippet claims a path its body contradicts.
`LangGraphAgent` moves from the v1 root entrypoint to
`@copilotkit/runtime/langgraph` on one page. Both spellings resolve, but the
subpath is the one that survives the v1 entrypoint; verified by typechecking
`LangGraphAgent` + v2 `CopilotRuntime` + `createCopilotEndpoint` together
against the published 1.68.3.
## Two mistakes worth recording, since both were caught by a check rather than by reading
A block regex scoped to the fence's opening indentation corrupted five
quickstart pages: their fences open and close at *different* indentation, so
the match ran past the closing backticks and re-indented the following
`</Step>` / `</Tab>` boundary into the code block. The five pages were reverted
and redone with a line-oriented pass that never re-indents anything and
re-emits the original closing line verbatim.
Every modified page is now checked structurally — fence-marker count and the
full set of JSX structural lines, indentation included, must be identical to
`HEAD`. All 33 pass. That check is what found the corruption; a diff review had
already missed it on the first pass.
## Verified
pnpm tsx scripts/doc-tests/extract.ts -> 2 snippets
pnpm tsx scripts/doc-tests/run.ts -> 2 passed, 0 failed
showcase/shell-docs: pnpm typecheck -> exit 0
showcase/shell-docs: pnpm lint -> exit 0 (pre-existing warnings only)
showcase/shell-docs: pnpm build -> exit 0
structural audit: 33/33 pages, fence + JSX structure identical to HEAD
Note this validates that the pages still build and that the one doctested
snippet compiles. It does not execute the other 37 fences. Their correctness
rests on Stage 0: the boilerplate they now contain is the text that was run in
`examples/shadcn`, and their agent wiring is untouched.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`snippets/copilot-runtime.mdx` calls itself "the recommended way to use
CopilotKit" and taught the v1 plain-POST route. A reader following it got an
endpoint that answers 405 on `GET /api/copilotkit` and does not route
`GET /api/copilotkit/info` at all, so nothing could discover the runtime.
The route fence is now the shape proved in `examples/shadcn`: catch-all path,
`createCopilotEndpoint`, a runner, and both verbs exported. The three other
fences on the page that were titled with the plain route path are retitled to
the catch-all path, so no snippet claims a path its body contradicts.
Also documents the two things the shape actually requires, both of which were
found by running it:
- `npm install @copilotkit/runtime hono` — `hono` is a dependency of the
runtime rather than a peer, so `hono/vercel` resolves under npm's flat
layout but not under pnpm.
- `useSingleEndpoint={false}` on `<CopilotKit>`. The provider defaults it to
`true` (single-route transport), which posts to the bare `runtimeUrl`; a
multi-route runtime answers that with 404. The Angular provider defaults its
transport to `"auto"` and needs no equivalent change, so that snippet is
unchanged.
## The snippet is now gated in CI
`scripts/doc-tests` already extracts fences tagged `doctest=` and, for
`component`, runs `tsc --noEmit` against real npm-installed dependencies — but
it could not handle a fence whose title is a path, which is exactly what a
Next.js route handler's title is. Two defects blocked it, both fixed here:
- `extract.ts` wrote the title as a path without creating intermediate
directories, so a titled route fence died on ENOENT.
- `run.ts` derived the npm package name from the snippet directory, and a
catch-all leaf directory is literally `[[...slug]]`, which npm rejects as an
invalid name. It also looked for `doctest.json` only in the snippet's own
directory, while the sidecar is copied once per page — so a nested snippet
silently installed no dependencies and failed with "Cannot find module".
With those fixed, the canonical route snippet is tagged `doctest="component"`
and typechecked in CI against the published `@copilotkit/runtime` 1.68.3 and
`hono`. This is the gate the docs did not have: snippet correctness no longer
rests on review alone.
Verified:
pnpm tsx scripts/doc-tests/extract.ts -> 2 snippets extracted
pnpm tsx scripts/doc-tests/run.ts -> 2 passed, 0 failed
mutation check: restoring the v1 import in the fence turns the run red
(1 passed, 1 failed), so the gate fails on the regression it exists to catch
vitest scripts/doc-tests/__tests__/extract.test.ts -> 10 passed
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Swapping the create_agent factory for create_react_agent (langgraph.prebuilt)
does not work: create_react_agent has no middleware= or system_prompt=
parameter and rejects state_schema=CopilotKitState, so following the comment
raises TypeError. It is also deprecated in favour of langchain.agents.create_agent.
Replace the misleading inline comment with an accurate note at all 7 sites
(supersedes the deprecated factory; accepts neither middleware= nor
system_prompt=), and fix the TypeScript snippets to reference createReactAgent
instead of the Python snake_case name.
Closes CopilotKit#6607
Tyler Slaton