CopilotKit

CopilotKit Documentation Audit

The docs are mid-migration from v1 to v2 and from a previous "BasicAgent/CoAgent" vocabulary to a new "BuiltInAgent/useAgent" one. The transitional state has produced multiple contradictions across pages — class names, provider names, CLI commands, import paths, and model identifier formats all disagree depending on which page a developer (or an agent) lands on first. The site does ship an llms.txt and an MCP server, which is good for agent indexing, but the underlying source disagreements will propagate straight into agent-generated code.

1. Built-in agent class is documented under two different names (critical)

Location: /built-in-agent/quickstart vs /whats-new/v1-50

Problem: /built-in-agent/quickstart instantiates the built-in agent as BuiltInAgent imported from @copilotkit/runtime/v2:

import { BuiltInAgent } from "@copilotkit/runtime/v2";
const builtInAgent = new BuiltInAgent({ model: "openai:gpt-5.4-mini" });

/whats-new/v1-50, the canonical "what shipped" page for the current major version, calls the same feature BasicAgent, imported from a different path:

import { BasicAgent } from "@copilotkit/runtime"
new BasicAgent({ model: "openai/gpt-5.4", ... })

Consequence: Only one of these imports actually exists in the published package. A developer (or AI coding agent) reading the v1.50 release notes copies BasicAgent and gets a "module has no exported member" error. The reverse happens for anyone reading the quickstart and then searching the changelog.

The fix: Pick one canonical name (BuiltInAgent if v2 is the current API; BasicAgent otherwise) and globally search/replace across /whats-new/v1-50, /built-in-agent/quickstart, the runtime reference, and any blog posts. Add a redirect/alias in the SDK if both names need to keep working.

2. Provider component name contradicts itself across four pages (critical)

Location: /migration-guides/migrate-to-v2, /reference/v2/components/CopilotKit, /reference/v2/hooks/useAgent, /troubleshooting/error-debugging, home page

Problem: The v2 migration guide explicitly tells developers to rename the provider:

Before: import { CopilotKit } from "@copilotkit/react-core"; After: import { CopilotKitProvider } from "@copilotkit/react-core/v2";

The v2 reference page for the same component says the opposite:

"This provider is shared across v1 and v2 APIs. It must be imported from the root package (@copilotkit/react-core), not from the v2 subpackage."

But two other v2 reference pages independently confirm the migration guide's name. /reference/v2/hooks/useAgent describes agentId as one that "must match an agent configured in CopilotKitProvider." /troubleshooting/error-debugging shows:

import { CopilotKitProvider } from "@copilotkit/react-core/v2";
<CopilotKitProvider runtimeUrl="/api/copilotkit" onError={(event) => { ... }}>

The home page mixes both worlds — it imports CopilotKit (v1 name) from the root package, then imports CopilotSidebar from @copilotkit/react-core/v2, and uses <CopilotKit> as the JSX tag.

Consequence: Three of the four v2 pages (migration guide, useAgent reference, error-debugging) say the provider is CopilotKitProvider; the dedicated reference page for the component says it's CopilotKit. A developer following the migration guide renames their provider; the reference says that path doesn't exist. The home page snippet won't survive the v2 migration as-shown. Agents reading these pages produce code that compiles against one page's contract and fails against another's.

The fix: Decide whether the provider in v2 is CopilotKit from the root package or CopilotKitProvider from /v2, then update the reference page and homepage to match the migration guide / useAgent reference / error-debugging examples (or vice versa). If both forms are valid (one is an alias), say so explicitly in every reference.

3. Model identifier strings disagree on separator format (critical)

Location: /built-in-agent/quickstart, /whats-new/v1-50

Problem: Two adjacent code examples use different separators in the model string:

• /built-in-agent/quickstart: model: "openai:gpt-5.4-mini" (colon)
• /whats-new/v1-50: model: "openai/gpt-5.4" (forward slash)

These are the only two model-string examples in the v1.50/v2 era of the docs, and they don't agree.

Consequence: Only one of provider:model or provider/model will be accepted by the runtime's model multiplexer. A developer who copies either snippet has a 50/50 chance of sending an unrecognized model string and getting a 400 from the upstream provider. An AI agent doing the same thing produces a non-running starter.

The fix: Pick one separator and document it once in a "model string format" section in the runtime reference. Update both examples to use the canonical form, and verify that gpt-5.4 and gpt-5.4-mini are both currently shipping identifiers in the runtime — if either is a placeholder, replace with a real model name.

4. CLI command differs across quickstarts — and /langgraph/ contradicts itself (critical)

Location: /quickstart, /threads, /langgraph/, /microsoft-agent-framework

Problem: The "first command a new user runs" is written four different ways across pages:

• /quickstart: npx copilotkit@latest create
• /threads: npx -y @copilotkit/cli@latest create
• /langgraph/: heading npx copilotkit create, with description "Starter app from running npx copilotkit@latest init"
• /microsoft-agent-framework: npx copilotkit create -f microsoft-agent-framework-dotnet

Three pages use the package name copilotkit; one uses the scoped @copilotkit/cli. Three use the subcommand create; the LangChain page uses both create (in the heading) and init (in the description directly underneath) — the page contradicts itself in adjacent lines.

Consequence: At least one of init and create will fail (init looks like a stale command from an older CLI). A developer who lands on /langgraph/ first sees two different commands on the same page and has no way to know which is current. Agents shown both options have no way to pick the right one.

The fix: Standardize on a single CLI invocation. Fix /langgraph/ so the heading and description match. Confirm whether the package is copilotkit or @copilotkit/cli — both currently appear under npx.

5. The v1 reference for useCopilotAction 404s but is still linked as the migration target (critical)

Location: /reference/useCopilotAction (404) — referenced from /reference/v2/hooks/useFrontendTool

Problem: The v2 useFrontendTool reference ends with a "Related" section that reads:

useCopilotAction -- v1 equivalent

That link points at /reference/useCopilotAction, which returns the 404 page ("Sorry, we couldn't find the page you're looking for").

Consequence: Anyone migrating off v1 — exactly the audience the migration guide and the v2 reference target — has no canonical reference for the API they're migrating from. AI agents that ground citations on the docs will return a 404 to users who ask "what was the v1 equivalent of useFrontendTool?"

The fix: Either restore the useCopilotAction reference page (with a "Deprecated — use useFrontendTool in v2" banner) or change the "v1 equivalent" link to a section inside the v2 page that documents the old signature alongside the new one.

6. Short-slug URL /migrate-to-v2 404s alongside the working /migration-guides/migrate-to-v2 (critical)

Location: /migrate-to-v2 (404) vs /migration-guides/migrate-to-v2 (works)

Problem: The canonical V2 migration guide lives at /migration-guides/migrate-to-v2. The shorter, more obvious URL /migrate-to-v2 returns the standard 404 page. There's no redirect from the short slug to the working one.

Consequence: Any blog post, internal link, social-media share, or AI-generated reference that uses the obvious-looking short URL hits a dead 404 instead of being redirected. For a migration guide — content that gets linked aggressively from third parties during a major version bump — this guarantees broken inbound links.

The fix: Add a 301/308 redirect from /migrate-to-v2 to /migration-guides/migrate-to-v2. While auditing, sweep for other short-slug variants (e.g., /migrate-to-1.10.X) that may have the same issue.

7. Threads docs contradict the v1.50 release page about whether threads ship today (significant)

Location: /threads vs /whats-new/v1-50

Problem: /threads documents useThreads, the CLI starter, and the Enterprise Intelligence Platform as a working, today-usable feature. /whats-new/v1-50 puts threads explicitly in a "Coming Soon" section:

"v1.50 is available now, with useAgent fully ready. The other features (listed below) will be added as they come out in the near future. Threads & Persistence …"

It then says:

"For production: Coming soon! - Use Copilot Cloud (managed) or Copilot Enterprise (self hosted) to persist threads to your own databases…"

/threads separately requires @copilotkit/react-core v1.56+, but the latest version with a release-notes page is v1.50.

Consequence: A developer reading the changelog believes threads aren't shipped, skips them, and builds their own persistence. Another developer reading /threads builds against a feature whose production story is "coming soon." The v1.56 floor mentioned on /threads has no matching release-notes page, so the developer can't tell what actually changed.

The fix: Update /whats-new/v1-50 to remove threads from "Coming Soon" if they're shipped, or add a clear "Beta — local dev only" banner to /threads if they're not. Either way, publish a whats-new/v1-56 (or whatever version actually introduced useThreads) page so the prerequisite is checkable.

8. Architecture page is effectively empty (significant)

Location: /learn/architecture

Problem: The entire page body is:

"How does CopilotKit work? CopilotKit is thoughtfully architected to scale with you, your teams, and your product. How does CopilotKit work? CopilotKit is thoughtfully architected to scale with you, your teams, and your product."

That's the same sentence twice with no diagram, no component breakdown, and no links into the AG-UI/runtime/provider layers. The /learn/ag-ui-protocol page is similarly thin — a paragraph that ends "To learn more, check out the AG-UI website."

Consequence: The "Learn" section is the front door for developers evaluating whether CopilotKit fits their architecture. As written it provides nothing. Agents asked "how does CopilotKit work?" have no source material to ground answers in and will fall back to marketing copy.

The fix: Replace the placeholder body with the actual architecture: provider → runtime endpoint → agent (AG-UI) → tools/state. The /backend/ag-ui page already has most of the content (event table, useAgent shape) — pull it forward into /learn/architecture or merge the two.

9. Feature-by-framework comparison matrix is not extractable as text (significant)

Location: Home page (/)

Problem: The "Feature comparison (by framework)" table lists 13 frameworks across the top and 9 features down the side (Generative UI, Frontend Tools, Tool Rendering, MCP Apps, A2UI, Shared State, Readables, Interrupts, State Streaming). The text extraction returns the headers but no body cells — there's no parseable indication of which framework supports which feature. Whether the rendered HTML uses icons that screen readers and AI agents can recover from is not visible from the scrape, but the matrix isn't surfacing as text in any case.

Consequence: The single most useful piece of selection guidance — "which framework supports the feature I need?" — is invisible to anything that consumes the text. AI agents indexing the page can't extract the matrix; screen readers risk getting only headers; anyone copying the table into another doc gets a blank grid.

The fix: Render the support matrix with inline text or text alternatives (✅/❌, "yes"/"no", or icons with explicit aria-label text) so it's machine-readable. Bonus: publish the same matrix as a JSON file referenced from llms.txt so coding agents can use it for routing.

10. v2 import paths inconsistent: home page vs migration guide vs /backend/ag-ui (significant)

Location: Home page (/), /migration-guides/migrate-to-v2, /backend/ag-ui

Problem: The "import everything from @copilotkit/react-core/v2" rule established by the migration guide is broken in two different places:

The flagship "app.tsx" example on the landing page imports from three different locations:

import { CopilotKit } from "@copilotkit/react-core";
import { CopilotSidebar } from "@copilotkit/react-core/v2";
import "@copilotkit/react-ui/v2/styles.css";

The migration guide says v2 collapses everything into @copilotkit/react-core/v2, including styles (@copilotkit/react-core/v2/styles.css — note react-core, not react-ui). So the homepage's @copilotkit/react-ui/v2/styles.css doesn't match.

Separately, /backend/ag-ui imports useAgent from the v1 path:

import { useAgent } from "@copilotkit/react-core";

But the v2 reference (/reference/v2/hooks/useFrontendTool, /troubleshooting/error-debugging) and the migration guide all use @copilotkit/react-core/v2. A core hook documented as a v2 feature is being imported from the v1 path on the page that explains how the protocol works.

Consequence: Copying the homepage snippet pulls a CSS path that, per the migration guide, is no longer canonical — if only one path is published in the package, the build errors. Copying the /backend/ag-ui snippet imports useAgent from the v1 path, contradicting every other v2 doc; if the v1 export isn't preserved, the import fails.

The fix: Pick the canonical paths — likely @copilotkit/react-core/v2/styles.css for styles and @copilotkit/react-core/v2 for useAgent, given the package consolidation — and use them consistently on the homepage, migration guide, /backend/ag-ui, and every per-framework quickstart.

11. Self-hosting guide pins to a release-candidate chart without explaining stability (minor)

Location: /premium/self-hosting

Problem: The self-hosting guide for the Enterprise Intelligence Platform tells operators to install from the OCI registry oci://ghcr.io/copilotkit/charts/intelligence and substitute "the latest released chart version … e.g. 0.1.0-rc.16" for the <chart-version> placeholder. The example version is a 0.1.0-rc.16 release candidate, but the page doesn't address what "rc" implies for a self-hosted production deployment, what stability guarantees exist, or when a 1.0.0 is expected.

Consequence: The audience for this page is operators evaluating a self-hosted enterprise deploy of a product they're paying for. Pinning the documented example to a 0.1.0-rc chart with no commentary on stability creates uncertainty about whether the platform is production-ready, and gives no signal about upgrade cadence.

The fix: Add a short "Chart stability & versioning" subsection that states the current stability level (RC vs GA), what guarantees apply at that level, and how operators should track GA releases. If the chart has been promoted past rc, update the example version.

12. _c suffix on premium APIs is never explained (minor)

Location: /reference/v2/components/CopilotKit, /migration-guides/migrate-to-1.10.X

Problem: Several public props and hooks ship with a _c suffix — guardrails_c, authConfig_c, useCopilotChatHeadless_c — and the suffix is never defined anywhere in the docs. Reading the surrounding text it appears to mean "canary" or "cloud-only," but a developer has to guess. The agents__unsafe_dev_only double-underscore prop on <CopilotKit> is similarly self-flagging without being documented.

Consequence: Developers don't know whether _c-suffixed APIs are stable, premium-gated, or about to be renamed. They show up in TypeScript autocomplete with no JSDoc convention to read.

The fix: Add a short "API stability suffixes" note to the top-level reference index explaining what _c, __unsafe_dev_only, and any other suffixes mean and what stability guarantees they carry. Better: enforce the convention in JSDoc so editors surface it inline.

What they do well

• They publish an llms.txt and an MCP server (https://mcp.copilotkit.ai/mcp, https://mcp.copilotkit.ai/llms.txt) explicitly aimed at AI coding agents — most peers don't.
• The error-debugging page has a real, structured error-code table (runtime_info_fetch_failed, agent_run_error_event, etc.) that's parseable by both humans and agents.
• The self-hosting page for the Intelligence Platform is concrete: Helm chart OCI URL, Postgres/Redis/OIDC requirements, port numbers per service.

Top 3 recommendations

1. Resolve the v1↔v2 vocabulary collision in one pass. The pairs BuiltInAgent/BasicAgent, CopilotKit/CopilotKitProvider, useCopilotAction/useFrontendTool, create/init, and react-core/v2/react-ui/v2/root are all currently inconsistent across pages — including within single pages (/langgraph/, /backend/ag-ui). Pick the canonical name and import path for each, do a doc-wide rename, and add aliases in the SDK so the deprecated form still imports with a console warning rather than a hard failure.
2. Fix the broken references and short-slug 404s. Restore (or redirect) /reference/useCopilotAction, add a redirect from /migrate-to-v2 to /migration-guides/migrate-to-v2, and replace the placeholder content on /learn/architecture and /learn/ag-ui-protocol with real diagrams and prose. These are the pages agents and evaluators land on first.
3. Make the framework support matrix machine-readable. Re-render the home-page comparison table with explicit text values, and publish the same matrix as JSON linked from llms.txt. Today the most useful piece of selection-guidance content on the site doesn't survive text extraction.