copilotkit-integrations

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CopilotKit Integrations

CopilotKit 集成

Live Documentation (MCP)

实时文档(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.
本插件包含一个MCP服务器(
copilotkit-docs
),提供
search-docs
search-code
工具,可用于查询CopilotKit实时文档和源代码,适用于查询框架特定的集成详情。
  • Claude Code: 由插件的
    .mcp.json
    自动配置,无需额外设置。
  • Codex: 需要手动配置,查看copilotkit-debug skill获取设置指南。

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 API route creates a
    CopilotRuntime
    that connects to the agent via an AG-UI client class
  4. Frontend -- React components use
    useAgent
    ,
    useFrontendTool
    ,
    useRenderToolCall
    , and
    useHumanInTheLoop
    to interact with the agent
CopilotKit通过AG-UI (Agent-UI) 协议连接外部Agent框架,这是一种流式协议,支持前端CopilotKit应用与后端Agent之间的双向通信。所有集成都遵循相同的架构模式:
  1. Agent服务端 -- 你的Agent框架以HTTP服务的形式运行(Python端通常是FastAPI/uvicorn,JS/TS端通常是Express/Next.js路由)
  2. AG-UI适配器 -- 特定于框架的适配器负责在Agent原生接口和AG-UI传输协议之间做转换
  3. CopilotKit runtime -- Next.js API路由创建一个
    CopilotRuntime
    实例,通过AG-UI客户端类连接到Agent
  4. 前端 -- React组件使用
    useAgent
    useFrontendTool
    useRenderToolCall
    useHumanInTheLoop
    与Agent交互

Supported Integrations

支持的集成

FrameworkLanguageAG-UI Client (route.ts)AG-UI Server AdapterAgent Port
LangGraph (Python, self-hosted)Python
LangGraphHttpAgent
from
@copilotkit/runtime/langgraph
ag-ui-langgraph
(
add_langgraph_fastapi_endpoint
)
8123
LangGraph (Python, LangGraph Platform)Python
LangGraphAgent
from
@copilotkit/runtime/langgraph
LangGraph Platform (managed)varies
LangGraph (JS)TypeScript
LangGraphAgent
from
@copilotkit/runtime/langgraph
Built into
@copilotkit/sdk-js/langgraph
8123
CrewAI FlowsPython
HttpAgent
from
@ag-ui/client
ag-ui-crewai
(
add_crewai_flow_fastapi_endpoint
)
8000
CrewAI CrewsPython
CrewAIAgent
from
@ag-ui/crewai
ag-ui-crewai
(
add_crewai_crew_fastapi_endpoint
)
8000
PydanticAIPython
HttpAgent
from
@ag-ui/client
pydantic-ai-slim[ag-ui]
(
agent.to_ag_ui()
)
8000
MastraTypeScript
MastraAgent
from
@ag-ui/mastra
Built into
@ag-ui/mastra
Next.js dev server
Google ADKPython
HttpAgent
from
@ag-ui/client
ag-ui-adk
(
add_adk_fastapi_endpoint
)
8000
LlamaIndexPython
LlamaIndexAgent
from
@ag-ui/llamaindex
llama-index-protocols-ag-ui
(
get_ag_ui_workflow_router
)
9000
AgnoPython
HttpAgent
from
@ag-ui/client
agno
(built-in
AgentOS
with
AGUI
interface)
8000
StrandsPython
HttpAgent
from
@ag-ui/client
ag_ui_strands
(
create_strands_app
)
8000
Microsoft Agent Framework (Python)Python
HttpAgent
from
@ag-ui/client
agent-framework-ag-ui
(
add_agent_framework_fastapi_endpoint
)
8000
Microsoft Agent Framework (.NET)C#
HttpAgent
from
@ag-ui/client
Microsoft.Agents.AI.Hosting.AGUI.AspNetCore
(
MapAGUI
)
8000
A2A MiddlewarePython + TS
A2AMiddlewareAgent
from
@ag-ui/a2a-middleware
Per-agent (mixed frameworks)9000-9002
MCP AppsTypeScript
BuiltInAgent
with
MCPAppsMiddleware
N/A (middleware on BuiltInAgent)3108
框架语言AG-UI Client (route.ts)AG-UI Server AdapterAgent 端口
LangGraph (Python, 自托管)Python
LangGraphHttpAgent
from
@copilotkit/runtime/langgraph
ag-ui-langgraph
(
add_langgraph_fastapi_endpoint
)
8123
LangGraph (Python, LangGraph Platform)Python
LangGraphAgent
from
@copilotkit/runtime/langgraph
LangGraph Platform (托管版)不固定
LangGraph (JS)TypeScript
LangGraphAgent
from
@copilotkit/runtime/langgraph
内置于
@copilotkit/sdk-js/langgraph
8123
CrewAI FlowsPython
HttpAgent
from
@ag-ui/client
ag-ui-crewai
(
add_crewai_flow_fastapi_endpoint
)
8000
CrewAI CrewsPython
CrewAIAgent
from
@ag-ui/crewai
ag-ui-crewai
(
add_crewai_crew_fastapi_endpoint
)
8000
PydanticAIPython
HttpAgent
from
@ag-ui/client
pydantic-ai-slim[ag-ui]
(
agent.to_ag_ui()
)
8000
MastraTypeScript
MastraAgent
from
@ag-ui/mastra
内置于
@ag-ui/mastra
Next.js 开发服务器
Google ADKPython
HttpAgent
from
@ag-ui/client
ag-ui-adk
(
add_adk_fastapi_endpoint
)
8000
LlamaIndexPython
LlamaIndexAgent
from
@ag-ui/llamaindex
llama-index-protocols-ag-ui
(
get_ag_ui_workflow_router
)
9000
AgnoPython
HttpAgent
from
@ag-ui/client
agno
(内置
AgentOS
支持
AGUI
接口)
8000
StrandsPython
HttpAgent
from
@ag-ui/client
ag_ui_strands
(
create_strands_app
)
8000
Microsoft Agent Framework (Python)Python
HttpAgent
from
@ag-ui/client
agent-framework-ag-ui
(
add_agent_framework_fastapi_endpoint
)
8000
Microsoft Agent Framework (.NET)C#
HttpAgent
from
@ag-ui/client
Microsoft.Agents.AI.Hosting.AGUI.AspNetCore
(
MapAGUI
)
8000
A2A 中间件Python + TS
A2AMiddlewareAgent
from
@ag-ui/a2a-middleware
各Agent对应实现(混合框架)9000-9002
MCP 应用TypeScript内置
BuiltInAgent
搭配
MCPAppsMiddleware
无(BuiltInAgent上的中间件)3108

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
使用以下决策树选择合适的集成方案:
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

通用AG-UI协议模式

Every integration shares these patterns on the frontend side.
所有集成在前端侧都遵循以下模式。

CopilotKit Provider (layout.tsx)

CopilotKit Provider (layout.tsx)

tsx
import { CopilotKitProvider } from "@copilotkit/react";
import "@copilotkit/react/styles.css";

export default function RootLayout({ children }) {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit" agent="my_agent_name">
      {children}
    </CopilotKitProvider>
  );
}
The
agent
prop must match the key used in
CopilotRuntime({ agents: { my_agent_name: ... } })
.
tsx
import { CopilotKitProvider } from "@copilotkit/react";
import "@copilotkit/react/styles.css";

export default function RootLayout({ children }) {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit" agent="my_agent_name">
      {children}
    </CopilotKitProvider>
  );
}
agent
属性必须和
CopilotRuntime({ agents: { my_agent_name: ... } })
中使用的键名一致。

API Route Pattern (route.ts)

API路由模式 (route.ts)

All integrations create a Next.js API route at
src/app/api/copilotkit/route.ts
:
tsx
import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { NextRequest } from "next/server";
// Import the appropriate agent class for your framework

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

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter: new ExperimentalEmptyAdapter(),
    endpoint: "/api/copilotkit",
  });
  return handleRequest(req);
};
所有集成都会在
src/app/api/copilotkit/route.ts
路径下创建一个Next.js API路由:
tsx
import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { NextRequest } from "next/server";
// 为你的框架导入对应的agent类

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

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter: new ExperimentalEmptyAdapter(),
    endpoint: "/api/copilotkit",
  });
  return handleRequest(req);
};

Shared State (useAgent)

共享状态 (useAgent)

tsx
const { state, setState } = useAgent<{ proverbs: string[] }>({
  name: "my_agent",
  initialState: { proverbs: [] },
});
tsx
const { state, setState } = useAgent<{ proverbs: string[] }>({
  name: "my_agent",
  initialState: { proverbs: [] },
});

Frontend Tools (useFrontendTool)

前端工具 (useFrontendTool)

tsx
useFrontendTool({
  name: "setThemeColor",
  parameters: [
    { name: "themeColor", description: "Hex color value", required: true },
  ],
  handler({ themeColor }) {
    setThemeColor(themeColor);
  },
});
tsx
useFrontendTool({
  name: "setThemeColor",
  parameters: [
    { name: "themeColor", description: "Hex color value", required: true },
  ],
  handler({ themeColor }) {
    setThemeColor(themeColor);
  },
});

Generative UI (useRenderToolCall)

生成式UI (useRenderToolCall)

tsx
useRenderToolCall({
  name: "get_weather",
  description: "Get weather for a location.",
  parameters: [{ name: "location", type: "string", required: true }],
  render: ({ args }) => <WeatherCard location={args.location} />,
}, []);
tsx
useRenderToolCall({
  name: "get_weather",
  description: "Get weather for a location.",
  parameters: [{ name: "location", type: "string", required: true }],
  render: ({ args }) => <WeatherCard location={args.location} />,
}, []);

Human in the Loop (useHumanInTheLoop)

人在回路 (useHumanInTheLoop)

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

Agent-Side State Management

Agent侧状态管理

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.
在Agent侧,共享状态的管理方式因框架而异,但协议是统一的——Agent会发出
STATE_SNAPSHOT
事件来更新前端。查看各集成指南获取框架特定的实现模式。

Key Packages

核心包

Frontend (all integrations):
  • @copilotkit/react
    -- hooks (
    useAgent
    ,
    useFrontendTool
    ,
    useRenderToolCall
    ,
    useHumanInTheLoop
    ) and UI components (
    CopilotSidebar
    ,
    CopilotPopup
    )
  • @copilotkit/runtime
    -- server runtime (
    CopilotRuntime
    ,
    ExperimentalEmptyAdapter
    )
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
前端(所有集成通用):
  • @copilotkit/react
    -- 钩子函数(
    useAgent
    useFrontendTool
    useRenderToolCall
    useHumanInTheLoop
    )和UI组件(
    CopilotSidebar
    CopilotPopup
  • @copilotkit/runtime
    -- 服务端runtime(
    CopilotRuntime
    ExperimentalEmptyAdapter
AG-UI客户端类(每个集成选一个):
  • @copilotkit/runtime/langgraph
    --
    LangGraphAgent
    LangGraphHttpAgent
  • @ag-ui/client
    --
    HttpAgent
    (通用,支持任意AG-UI服务端)
  • @ag-ui/crewai
    --
    CrewAIAgent
  • @ag-ui/mastra
    --
    MastraAgent
  • @ag-ui/llamaindex
    --
    LlamaIndexAgent
  • @ag-ui/a2a-middleware
    --
    A2AMiddlewareAgent
  • @ag-ui/mcp-apps-middleware
    --
    MCPAppsMiddleware