copilotkit-integrations

CopilotKit 集成

实时文档（MCP）

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

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

概述

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 API 路由创建一个 CopilotRuntime，通过 AG-UI 客户端类连接 Agent
4. 前端——React 组件使用 useAgent、useFrontendTool、useRenderToolCall 和 useHumanInTheLoop 与 Agent 交互

支持的集成

框架	语言	AG-UI 客户端（route.ts）	AG-UI 服务端适配器	Agent 端口
LangGraph（Python，可自托管）	Python	来自 @copilotkit/runtime/langgraph 的 LangGraphHttpAgent	ag-ui-langgraph（add_langgraph_fastapi_endpoint）	8123
LangGraph（Python，LangGraph Platform）	Python	来自 @copilotkit/runtime/langgraph 的 LangGraphAgent	LangGraph Platform（托管）	不固定
LangGraph（JS）	TypeScript	来自 @copilotkit/runtime/langgraph 的 LangGraphAgent	内置于 @copilotkit/sdk-js/langgraph	8123
CrewAI Flows	Python	来自 @ag-ui/client 的 HttpAgent	ag-ui-crewai（add_crewai_flow_fastapi_endpoint）	8000
CrewAI Crews	Python	来自 @ag-ui/crewai 的 CrewAIAgent	ag-ui-crewai（add_crewai_crew_fastapi_endpoint）	8000
PydanticAI	Python	来自 @ag-ui/client 的 HttpAgent	pydantic-ai-slim[ag-ui]（agent.to_ag_ui()）	8000
Mastra	TypeScript	来自 @ag-ui/mastra 的 MastraAgent	内置于 @ag-ui/mastra	Next.js 开发服务
Google ADK	Python	来自 @ag-ui/client 的 HttpAgent	ag-ui-adk（add_adk_fastapi_endpoint）	8000
LlamaIndex	Python	来自 @ag-ui/llamaindex 的 LlamaIndexAgent	llama-index-protocols-ag-ui（get_ag_ui_workflow_router）	9000
Agno	Python	来自 @ag-ui/client 的 HttpAgent	agno（内置 AgentOS，具有 AGUI 接口）	8000
Strands	Python	来自 @ag-ui/client 的 HttpAgent	ag_ui_strands（create_strands_app）	8000
Microsoft Agent Framework（Python）	Python	来自 @ag-ui/client 的 HttpAgent	agent-framework-ag-ui（add_agent_framework_fastapi_endpoint）	8000
Microsoft Agent Framework（.NET）	C#	来自 @ag-ui/client 的 HttpAgent	Microsoft.Agents.AI.Hosting.AGUI.AspNetCore（MapAGUI）	8000
A2A Middleware	Python + TS	来自 @ag-ui/a2a-middleware 的 A2AMiddlewareAgent	每个 Agent 单独配置（混合框架）	9000-9002
MCP Apps	TypeScript	使用 MCPAppsMiddleware 的 BuiltInAgent	不适用（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 { 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.ts）

所有集成都在 src/app/api/copilotkit/route.ts 创建一个 Next.js API 路由：

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

共享状态（useAgent）

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

前端工具（useFrontendTool）

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

生成式 UI（useRenderToolCall）

useRenderToolCall({
  name: "get_weather",
  description: "Get weather for a location.",
  parameters: [{ name: "location", type: "string", required: true }],
  render: ({ args }) => <WeatherCard location={args.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 -- Hooks（useAgent、useFrontendTool、useRenderToolCall、useHumanInTheLoop）和 UI 组件（CopilotSidebar、CopilotPopup）
• @copilotkit/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