Menu
Use when migrating a CopilotKit v1 application to v2 -- updating package imports, replacing deprecated hooks and components, switching from GraphQL runtime to AG-UI protocol runtime, and resolving breaking API changes.
| name | copilotkit-upgrade |
| description | Use when migrating a CopilotKit v1 application to v2 -- updating package imports, replacing deprecated hooks and components, switching from GraphQL runtime to AG-UI protocol runtime, and resolving breaking API changes. |
| version | 1.0.0 |
This plugin includes an MCP server (copilotkit-docs) that provides search-docs and search-code tools for querying live CopilotKit documentation and source code. Useful for looking up current v2 API signatures during migration.
.mcp.json -- no setup needed.CopilotKit v2 is a ground-up rewrite built on the AG-UI protocol (@ag-ui/client / @ag-ui/core). Users continue to install and import @copilotkit/* packages -- the v2 changes are exposed through the same package names with updated APIs (new hook names, component names, runtime configuration). The @copilotkit/* namespace is an internal implementation detail that users never interact with.
Scan the codebase for all v1 imports and API usage:
@copilotkit/react-core -> hooks, CopilotKit provider, types
@copilotkit/react-ui -> CopilotChat, CopilotPopup, CopilotSidebar
@copilotkit/react-textarea -> CopilotTextarea (removed in v2)
@copilotkit/runtime -> CopilotRuntime, service adapters, framework integrations
@copilotkit/runtime-client-gql -> GraphQL client, message types
@copilotkit/shared -> utility types, constants
@copilotkit/sdk-js -> LangGraph/LangChain SDK
Key hooks and components to find and replace:
| v1 API | v2 Replacement |
|---|---|
useCopilotAction | useFrontendTool |
useCopilotReadable | useAgentContext |
useCopilotChat | useAgent + useSuggestions |
useCoAgent | useAgent |
useCoAgentStateRender | useRenderToolCall / useRenderActivityMessage |
useLangGraphInterrupt | useInterrupt |
useCopilotChatSuggestions | useConfigureSuggestions + useSuggestions |
useCopilotAdditionalInstructions | useAgentContext |
useMakeCopilotDocumentReadable | useAgentContext |
CopilotKit (provider) | CopilotKitProvider |
CopilotTextarea | Removed -- use standard textarea + useFrontendTool |
Refer to references/v1-to-v2-migration.md for detailed before/after code examples.
The @copilotkit/* package names stay the same. Update to the latest v2 versions:
@copilotkit/react-core -> @copilotkit/react (consolidated into one package)
@copilotkit/react-ui -> @copilotkit/react (consolidated into one package)
@copilotkit/react-textarea -> removed (no v2 equivalent)
@copilotkit/runtime -> @copilotkit/runtime (same package, new agent-based API)
@copilotkit/runtime-client-gql -> removed (replaced by AG-UI protocol, re-exported from @copilotkit/react)
@copilotkit/shared -> @copilotkit/shared (same package)
@copilotkit/sdk-js -> @copilotkit/agent (new package for agent definitions)
The v1 CopilotRuntime accepted service adapters (OpenAI, Anthropic, LangChain, etc.) and endpoint definitions. The v2 CopilotRuntime accepts AG-UI AbstractAgent instances directly.
v1 pattern (service adapter + endpoints):
import { CopilotRuntime, OpenAIAdapter } from "@copilotkit/runtime";
const runtime = new CopilotRuntime({ actions: [...] });
// used with copilotKitEndpoint() for Next.js, Express, etc.
v2 pattern (agents + Hono endpoint):
import { CopilotRuntime, createCopilotEndpoint } from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/agent";
const runtime = new CopilotRuntime({
agents: { myAgent: new BuiltInAgent({ model: "openai:gpt-4o" }) },
});
const app = createCopilotEndpoint({ runtime, basePath: "/api/copilotkit" });
v1:
import { CopilotKit } from "@copilotkit/react-core";
<CopilotKit runtimeUrl="/api/copilotkit">{children}</CopilotKit>;
v2:
import { CopilotKitProvider } from "@copilotkit/react";
<CopilotKitProvider runtimeUrl="/api/copilotkit">
{children}
</CopilotKitProvider>;
| Concept | v1 | v2 |
|---|---|---|
| Package scope | @copilotkit/* | @copilotkit/* (same scope, updated APIs) |
| Protocol | GraphQL | AG-UI (SSE) |
| Provider component | CopilotKit | CopilotKitProvider |
| Define frontend tool | useCopilotAction | useFrontendTool |
| Share app state | useCopilotReadable | useAgentContext |
| Agent interaction | useCoAgent | useAgent |
| Handle interrupts | useLangGraphInterrupt | useInterrupt |
| Render tool calls | useCopilotAction({ render }) | useRenderToolCall |
| Chat suggestions | useCopilotChatSuggestions | useConfigureSuggestions |
| Runtime class | CopilotRuntime (adapters) | CopilotRuntime (agents) |
| Endpoint setup | copilotKitEndpoint() | createCopilotEndpoint() |
| Agent definition | LangGraphAgent endpoint | AbstractAgent / BuiltInAgent |
| Chat components | CopilotChat, CopilotPopup, CopilotSidebar | CopilotChat, CopilotPopup, CopilotSidebar (from @copilotkit/react) |
Use when adding CopilotKit to an existing project or bootstrapping a new CopilotKit project from scratch. Covers framework detection, package installation, runtime wiring, provider setup, and first working chat integration.
Use when building custom agent backends, implementing the AG-UI protocol, debugging streaming issues, or understanding how agents communicate with frontends. Covers event types, SSE transport, AbstractAgent/HttpAgent patterns, state synchronization, tool calls, and human-in-the-loop flows.
Use when contributing to the CopilotKit open-source project — forking, cloning, setting up the monorepo, creating branches, running tests, and submitting pull requests against CopilotKit/CopilotKit.
Use when diagnosing CopilotKit issues -- runtime connectivity failures, agent not responding, streaming errors, tool execution problems, transcription failures, version mismatches, and AG-UI event tracing.
Use when building AI-powered features with CopilotKit v2 -- adding chat interfaces, registering frontend tools, sharing application context with agents, handling agent interrupts, and working with the CopilotKit runtime.
Use when wiring an external agent framework (LangGraph, CrewAI, PydanticAI, Mastra, ADK, LlamaIndex, Agno, Strands, Microsoft Agent Framework, or others) into a CopilotKit application via the AG-UI protocol.