copilotkit-integrations

CopilotKit Integrations

Live Documentation (MCP)

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 framework-specific integration details.

• Claude Code: Auto-configured by the plugin's .mcp.json -- no setup needed.
• Codex: Requires manual configuration. See the copilotkit-debug skill for setup instructions.

Overview

CopilotKit connects to external agent frameworks through the AG-UI (Agent-UI) protocol -- a streaming protocol that enables bidirectional communication between a frontend CopilotKit application and a backend agent. Every integration follows the same architectural pattern:

1. Agent server -- your agent framework runs as an HTTP server (usually FastAPI/uvicorn for Python, or an Express/Next.js route for JS/TS)
2. AG-UI adapter -- a framework-specific adapter translates between the agent's native interface and the AG-UI wire protocol
3. CopilotKit runtime -- the Next.js catch-all API route creates a CopilotRuntime that connects to the agent via an AG-UI client class, mounted with the V2 multi-route Hono handler
4. Frontend -- React components use useAgent, useFrontendTool, useRenderTool, and useHumanInTheLoop to interact with the agent

Supported Integrations

Decision Tree

Use this to pick the right integration:

Is your agent written in TypeScript/JavaScript?
  YES --> Is it a Mastra agent?
    YES --> Use Mastra integration (references/integrations/mastra.md)
    NO  --> Is it a LangGraph JS agent?
      YES --> Use LangGraph JS integration (references/integrations/langgraph.md, JS section)
      NO  --> Use BuiltInAgent with MCP Apps middleware or HttpAgent
  NO (Python or .NET) -->
    Which framework?
      LangGraph     --> references/integrations/langgraph.md
      CrewAI        --> references/integrations/crewai.md
      PydanticAI    --> references/integrations/pydantic-ai.md
      Google ADK    --> references/integrations/adk.md
      LlamaIndex    --> references/integrations/llamaindex.md
      Agno          --> references/integrations/agno.md
      Strands       --> references/integrations/strands.md
      MS Agent Fw   --> references/integrations/ms-agent-framework.md
      Multiple agents (A2A) --> references/integrations/a2a.md

Common AG-UI Protocol Patterns

Every integration shares these patterns on the frontend side.

CopilotKit Provider (layout.tsx)

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

export default function RootLayout({ children }) {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit" useSingleEndpoint={false}>
      {children}
    </CopilotKit>
  );
}

The provider component is CopilotKit (imported from @copilotkit/react-core/v2). There is no agent prop -- agents are selected per-hook via agentId (matching a key from CopilotRuntime({ agents: { ... } })). Set useSingleEndpoint={false} so the v1-compat bridge uses multi-route transport against the catch-all backend route below; omitting it defaults to single-route, which a multi-route backend 404s.

API Route Pattern (route.ts)

All integrations create a Next.js catch-all API route at src/app/api/copilotkit/[[...slug]]/route.ts using the V2 multi-route Hono handler:

import {
  CopilotRuntime,
  createCopilotHonoHandler,
  InMemoryAgentRunner,
} from "@copilotkit/runtime/v2";
import { handle } from "hono/vercel";
// Import the appropriate agent class for your framework

const runtime = new CopilotRuntime({
  agents: {
    default: new SomeAgentClass({ url: "http://localhost:8000/" }),
  },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotHonoHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);
export const PATCH = handle(app);
export const DELETE = handle(app);

Use createCopilotHonoHandler (the non-deprecated factory; createCopilotEndpoint is an alias). The frontend selects this agent via agentId: "default".

Shared State (useAgent)

useAgent returns { agent } only. Read state via agent.state and write via agent.setState:

const { agent } = useAgent({ agentId: "default" });
const state = (agent.state as { proverbs: string[] } | undefined) ?? {
  proverbs: [],
};
const setState = (next: { proverbs: string[] }) => agent.setState(next);

Frontend Tools (useFrontendTool)

import { z } from "zod";

useFrontendTool({
  name: "setThemeColor",
  parameters: z.object({
    themeColor: z.string().describe("The theme color to set."),
  }),
  handler: async ({ themeColor }) => {
    setThemeColor(themeColor);
    return `Set theme color to ${themeColor}`;
  },
});

Generative UI (useRenderTool)

import { z } from "zod";

useRenderTool(
  {
    name: "get_weather",
    parameters: z.object({ location: z.string() }),
    render: ({ parameters }) => <WeatherCard location={parameters.location} />,
  },
  [],
);

Human in the Loop (useHumanInTheLoop)

useHumanInTheLoop(
  {
    name: "go_to_moon",
    description: "Go to the moon on request.",
    render: ({ respond, status }) => (
      <MoonCard status={status} respond={respond} />
    ),
  },
  [],
);

Agent-Side State Management

On the agent side, shared state is managed differently per framework, but the protocol is the same -- agents emit STATE_SNAPSHOT events to update the frontend. See each integration guide for framework-specific patterns.

Key Packages

Frontend (all integrations):

• @copilotkit/react-core/v2 -- provider (CopilotKit), hooks (useAgent, useFrontendTool, useRenderTool, useHumanInTheLoop), and chat components (CopilotChat, CopilotSidebar, CopilotPopup). Styles: import "@copilotkit/react-core/v2/styles.css".
• @copilotkit/runtime/v2 -- server runtime (CopilotRuntime, createCopilotHonoHandler, InMemoryAgentRunner)

AG-UI client classes (choose one per integration):

• @copilotkit/runtime/langgraph -- LangGraphAgent, LangGraphHttpAgent
• @ag-ui/client -- HttpAgent (generic, works with any AG-UI server)
• @ag-ui/crewai -- CrewAIAgent
• @ag-ui/mastra -- MastraAgent
• @ag-ui/llamaindex -- LlamaIndexAgent
• @ag-ui/a2a-middleware -- A2AMiddlewareAgent
• @ag-ui/mcp-apps-middleware -- MCPAppsMiddleware