copilotkit-integrations

CopilotKit 集成

实时文档 (MCP)

该插件包含一个 MCP 服务（copilotkit-docs），提供 search-docs 和 search-code 工具，用于查询实时 CopilotKit 文档和源代码。适用于查找特定框架的集成细节。

• Claude Code： 由插件的 .mcp.json 自动配置——无需手动设置。
• Codex： 需要手动配置。设置说明请参阅 copilotkit-debug skill。

概述

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 运行时——Next.js 的 catch-all API 路由创建一个 CopilotRuntime，通过 AG-UI 客户端类连接到 Agent，并使用 V2 多路由 Hono 处理器挂载
4. 前端——React 组件使用 useAgent、useFrontendTool、useRenderTool 和 useHumanInTheLoop 与 Agent 交互

支持的集成

框架	语言	AG-UI 客户端 (route.ts)	AG-UI 服务端适配器	Agent 端口
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 Flows	Python	HttpAgent from @ag-ui/client	ag-ui-crewai (add_crewai_flow_fastapi_endpoint)	8000
CrewAI Crews	Python	CrewAIAgent from @ag-ui/crewai	ag-ui-crewai (add_crewai_crew_fastapi_endpoint)	8000
PydanticAI	Python	HttpAgent from @ag-ui/client	pydantic-ai-slim[ag-ui] (AGUIAdapter.dispatch_request())	8000
Mastra	TypeScript	MastraAgent from @ag-ui/mastra	内置于 @ag-ui/mastra	Next.js 开发服务器
Google ADK	Python	HttpAgent from @ag-ui/client	ag-ui-adk (add_adk_fastapi_endpoint)	8000
LlamaIndex	Python	LlamaIndexAgent from @ag-ui/llamaindex	llama-index-protocols-ag-ui (get_ag_ui_workflow_router)	9000
Agno	Python	HttpAgent from @ag-ui/client	agno (内置 AgentOS，带 AGUI 接口)	8000
Strands	Python	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 Middleware	Python + TS	A2AMiddlewareAgent from @ag-ui/a2a-middleware	按 Agent 而定 (混合框架)	9000-9002
MCP Apps	TypeScript	BuiltInAgent 搭配 MCPAppsMiddleware	N/A (BuiltInAgent 上的中间件)	3108

决策树

用它来选择合适的集成：

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

常见 AG-UI 协议模式

每个集成在前端侧都共享这些模式。

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>
  );
}

Provider 组件是 CopilotKit（从 @copilotkit/react-core/v2 导入）。没有 agent 属性 —— Agent 通过每个 hook 上的 agentId 来选择（对应 CopilotRuntime({ agents: { ... } }) 中的一个键）。useSingleEndpoint={false} 将多路由传输固定在下方全捕获后端路由上。它是可选的 —— 省略它会让 provider 自动检测模式 —— 但固定它可以跳过检测探测。

API 路由模式（route.ts）

所有集成都会在 src/app/api/copilotkit/[[...slug]]/route.ts 创建一个 Next.js 全捕获 API 路由，使用 V2 多路由 Hono 处理器：

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);

使用 createCopilotHonoHandler（未弃用的工厂函数；createCopilotEndpoint 是其别名）。前端通过 agentId: "default" 选择该 Agent。

共享状态（useAgent）

useAgent 仅返回 { agent }。通过 agent.state 读取状态，通过 agent.setState 写入状态：

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

前端工具（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}`;
  },
});

生成式 UI（useRenderTool）

import { z } from "zod";

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

人在回路（useHumanInTheLoop）

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

Agent 端状态管理

在 Agent 端，共享状态的管理方式因框架而异，但协议是相同的 —— Agent 发出 STATE_SNAPSHOT 事件来更新前端。请参阅各集成指南了解框架特定的模式。

关键包

前端（所有集成）：

• @copilotkit/react-core/v2 —— provider（CopilotKit）、hooks（useAgent、useFrontendTool、useRenderTool、useHumanInTheLoop）以及聊天组件（CopilotChat、CopilotSidebar、CopilotPopup）。样式：import "@copilotkit/react-core/v2/styles.css"。
• @copilotkit/runtime/v2 —— 服务端运行时（CopilotRuntime、createCopilotHonoHandler、InMemoryAgentRunner）

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