使用 LangGraph + FastAPI + CopilotKit 搭建 Agent 前端：从零运行 langgraph-fastapi 集成示例

【免费下载链接】CopilotKit The Frontend Stack for Agents & Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol 项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit

导读

本指南基于 CopilotKit 仓库中的 langgraph-fastapi 集成示例，完整讲解如何把一个基于 LangGraph 构建的 Python Agent，通过 FastAPI 与 AG-UI 协议接入 CopilotKit 的 React 前端。你将掌握：本地一键启动前后端、LangGraph 图与工具（To-Do、数据查询、A2UI 生成式 UI）的挂载方式、CopilotRuntime 端点的配置原理，以及 Docker 化部署与常见排错。读完即可在本仓库基础上快速搭出自己第一个"CopilotKit + LangGraph"完整应用。

示例定位：CopilotKit 与 LangGraph 的 FastAPI 集成起点

在 CopilotKit 仓库的 examples/integrations/ 目录下，langgraph-fastapi 是一个专门面向 LangGraph Agent + FastAPI 服务的 Starter 模板。它给出了一个开箱即用的技术栈：

• 前端：Next.js（App Router）+ CopilotKit React SDK，提供聊天界面、线程抽屉、A2UI 画布；
• 后端：Python FastAPI + uvicorn 承载 LangGraph Agent，并通过 ag-ui-langgraph 暴露符合 AG-UI 协议的接口；
• 通信桥梁：@copilotkit/runtime 在 Next.js 的 /api/copilotkit 路由上建立 CopilotRuntime，把浏览器请求转发给 Python Agent。

与仓库中同目录的 langgraph-python 示例 不同，本示例不依赖 LangGraph Platform / langgraph-cli dev，而是直接以 uvicorn + FastAPI 方式运行 agent（参见 agent/main.py 中的注释与实现），因此更适合自托管、容器化以及自定义 HTTP 服务层的场景。

环境准备（Prerequisites）

原 README 列出的前置条件如下，本小节结合当前仓库实际文件做对齐说明：

项目	要求	仓库实际情况
Node.js	18+	仓库示例使用 Next.js 16.1.6（见 package.json），建议使用较新 LTS
Python	3.8+（README 说法）	实际 pyproject.toml 声明 requires-python = ">=3.12"，请以 3.12+ 为准
Python 包管理器	Poetry 2+（README 说法）	当前仓库实际使用 uv（存在 uv.lock，install:agent 脚本执行 uv sync）；Poetry 仅保留在排错建议中
前端包管理器	npm / pnpm / yarn / bun 任选	仓库默认 npm，dev 脚本依赖 concurrently
模型密钥	OpenAI API Key	Agent 图使用 ChatOpenAI，还需能访问所配置模型

说明：README 中 "Python 3.8+ / Poetry 2+" 属于模板遗留信息，实际工程以 uv 与 Python >= 3.12 为准，请勿混用两套环境。

快速开始：四步启动一个完整的 Agent 应用

第 1 步：安装前端依赖

在 examples/integrations/langgraph-fastapi 目录下，任选一个包管理器：

# npm（默认）
npm install

# pnpm
pnpm install

# yarn
yarn install

# bun
bun install

值得注意的是，package.json 中定义了 postinstall: "npm run install:agent"，即前端依赖安装完成后会自动联动安装 Python agent 依赖，无需再手动执行第 2 步；若你跳过 postinstall 或使用其他包管理器，则按第 2 步手动安装。

第 2 步：安装 Python Agent 依赖

# npm（默认）
npm run install:agent

# pnpm
pnpm install:agent

# yarn
yarn install:agent

# bun
bun run install:agent

该命令等价于 cd agent && uv sync，会依据 agent/pyproject.toml 安装如下关键依赖：

• copilotkit==0.1.96：Python 侧 SDK，提供 LangGraphAGUIAgent、CopilotKitMiddleware、StateStreamingMiddleware 与 a2ui 渲染工具；
• langgraph==1.1.6、langchain==1.2.15、langchain-openai==1.1.9：Agent 运行时与模型接入；
• ag-ui-langgraph[fastapi]==0.0.43：把 LangGraph 图包装成 AG-UI 协议端点（含 FastAPI 扩展）；
• fastapi>=0.115.5,<1.0.0、uvicorn>=0.29.0,<1.0.0：HTTP 服务；
• ag-ui-protocol==0.1.19：AG-UI 协议类型定义。

第 3 步：配置 OpenAI API Key

README 给出的做法是写入 agent/.env：

echo 'OPENAI_API_KEY=your-openai-api-key-here' > agent/.env

从 agent/main.py 的启动逻辑看，.env 的加载顺序是：先尝试加载 demo 项目根目录（agent/ 的上一级）下的 .env，再尝试当前目录 .env，最后才回退到 load_dotenv() 默认行为。也就是说，把密钥放在 examples/integrations/langgraph-fastapi/.env 也同样生效，且必须在 from src.agent import graph 之前完成加载（因为模块导入时会构造 ChatOpenAI，需要环境变量已就绪）。

第 4 步：启动开发服务器

# npm（默认）
npm run dev

# pnpm
pnpm dev

# yarn
yarn dev

# bun
bun run dev

dev 脚本使用 concurrently 同时拉起两个进程（见 package.json）：

• dev:ui：next dev --turbopack，启动 Next.js 前端；
• dev:agent：cd agent && uv run main.py，启动 FastAPI agent 服务，默认端口 8123。

启动后，前端默认运行在 Next.js 开发端口（通常为 http://localhost:3000），Agent 服务运行在 http://localhost:8123，Agent 服务还额外提供了 GET /health 健康检查端点（见 agent/main.py）。

可用脚本一览

以下脚本均可在 examples/integrations/langgraph-fastapi 目录下用你选择的包管理器执行：

脚本	命令（npm 示例）	作用
dev	npm run dev	同时启动 UI 与 agent 两个开发服务器
dev:debug	npm run dev:debug	以 LOG_LEVEL=debug 环境变量启动开发模式，输出调试日志
dev:ui	npm run dev:ui	仅启动 Next.js UI（next dev --turbopack）
dev:agent	npm run dev:agent	仅启动 LangGraph agent 服务（cd agent && uv run main.py）
build	npm run build	构建 Next.js 生产包
start	npm run start	启动 Next.js 生产服务器
install:agent	npm run install:agent	安装 agent 的 Python 依赖（cd agent && uv sync）

前端实现拆解：UI、运行时端点与无头聊天

页面入口：一个"聊天 + 画布"的完整工作区

主界面定义在 src/app/page.tsx。它使用一个**非受控（uncontrolled）**的 CopilotChatConfigurationProvider 持有活动线程，配合 SDK 自带的 CopilotThreadsDrawer（线程抽屉，支持切换历史线程与"新建线程"），左侧为 CopilotChat 聊天面板，右侧为 ExampleCanvas 应用画布。

代码注释明确指出：此处必须使用非受控 Provider（不传 threadId），否则受控状态下"新建线程"无法重置聊天。聊天与画布共享同一活动线程——画布中的 useAgent() 会回退到 Provider 的线程上下文，因此 A2UI 渲染的组件与对话保持同步。

聊天组件还开启了附件上传（attachments={{ enabled: true }}）并自定义了输入框样式（input={{ disclaimer: () => null, className: "pb-6" }}）。界面主题、侧边栏外观、前端 Actions 均可在此基础上自由定制，这也是 README 中"Modify the theme colors / Add new frontend actions / Customize the sidebar"对应的位置。

运行时端点：CopilotRuntime 如何连到 FastAPI Agent

关键桥接文件是 src/app/api/copilotkit/[[...slug]]/route.ts。它：

1. 用 LangGraphHttpAgent 指向 AGENT_URL（默认 http://localhost:8123/），直接以 AG-UI 协议访问 FastAPI 服务；
2. 用 CopilotRuntime 聚合 agents、开启 openGenerativeUI: true、配置 a2ui（本例关闭工具自动注入 injectA2UITool: false，因为 Agent 侧已显式提供 A2UI 工具）；
3. 通过 Hono 的 handle 导出 GET/POST/PATCH/DELETE 路由，把 /api/copilotkit 作为 CopilotRuntime 的 basePath。

文件内注释特别强调：因为 FastAPI 侧由 ag-ui-langgraph 直接讲 AG-UI 协议，所以这里必须使用 HttpAgent 而非 LangGraphAgent（后者面向 LangGraph Platform / langgraph-cli dev，协议不同）。

可选：无头聊天模式

若不想使用开箱即用的聊天 UI，可参考 src/components/headless-chat.tsx：通过 useAgent() 拿到 agent 实例，手动 addMessage() 加入用户消息后调用 runAgent() 触发推理，再自行渲染 agent.messages。这展示了 CopilotKit React SDK 的编程式控制能力，适合需要完全自定义聊天界面的场景。

Agent 后端拆解：LangGraph 图、状态流式与 A2UI

FastAPI 入口与 AG-UI 端点挂载

agent/main.py 是 Python 服务入口，核心逻辑只有三段：

from fastapi import FastAPI
from src.agent import graph
from copilotkit import LangGraphAGUIAgent
from ag_ui_langgraph import add_langgraph_fastapi_endpoint

app = FastAPI()

add_langgraph_fastapi_endpoint(
    app=app,
    agent=LangGraphAGUIAgent(
        name="sample_agent",
        description="An example agent to use as a starting point for your own agent.",
        graph=graph,
    ),
    path="/",
)

即把 src.agent 中导出的 graph 包装成 LangGraphAGUIAgent，再通过 add_langgraph_fastapi_endpoint 挂载到根路径 /，对外即成为符合 AG-UI 协议的 Agent 端点。默认端口由环境变量 PORT 控制，回退到 8123。

LangGraph 图：工具、中间件与状态

agent/src/agent.py 是图的定义处，要点如下：

• 模型：ChatOpenAI(model="gpt-5.4", model_kwargs={"parallel_tool_calls": False})，关闭并行工具调用，保证 A2UI/状态类工具按顺序执行；
• 工具清单：query_data（CSV 数据查询）、todo_tools（To-Do 管理）、generate_a2ui（动态 A2UI）、search_flights（固定 schema A2UI）；
• 中间件：CopilotKitMiddleware() 负责 AG-UI 上下文注入；StateStreamingMiddleware(StateItem(state_key="todos", tool="manage_todos", tool_argument="todos")) 负责把 manage_todos 工具写入的 todos 字段实时流式同步给前端；
• 状态 schema：使用 AgentState（继承 LangChain 的 AgentState 并扩展 todos: list[Todo] 字段，见 agent/src/todos.py）；
• checkpointer：由于是 uvicorn + ag-ui-langgraph 方式运行（非 langgraph-cli dev 自带 checkpointer），图显式传入 MemorySaver()，用于进程内线程状态持久化；
• 系统提示词：约束模型输出 1~2 句简洁回答，并给出工具使用指引（航班→search_flights，仪表盘/富 UI→generate_a2ui，图表→先 query_data，To-Do→先启用 app 模式等）。

To-Do 工具：用 LangGraph Command 更新状态

agent/src/todos.py 展示了"工具内修改 Agent 状态"的标准写法：manage_todos 为每个缺少 id 的待办生成 uuid4，然后返回 Command(update={"todos": todos, "messages": [ToolMessage(...)]}) 直接更新图状态；get_todos 则从 runtime.state 读取当前待办。这种模式配合 StateStreamingMiddleware，可实现 To-Do 看板（见 src/components/example-canvas/）的实时刷新。

两种 A2UI 生成式 UI 方式

示例同时演示了两种让 Agent 生成前端 UI 的方式，均基于 AG-UI 的 A2UI 能力（前端 CopilotRuntime 已开启 openGenerativeUI，且 @copilotkit/a2ui-renderer 负责渲染）：

1. 固定 schema（a2ui_fixed_schema.py）：search_flights 从 flight_schema.json 加载固定组件 schema（见 agent/src/a2ui/schemas/flight_schema.json），每次调用只更新数据。工具内部通过 a2ui.create_surface、a2ui.update_components、a2ui.update_data_model 组装 a2ui_operations，并以 a2ui.render() 返回，中间件检测到 TOOL_CALL_RESULT 后自动渲染航班卡片。

2. 动态 schema（a2ui_dynamic_schema.py）：generate_a2ui 用二级 LLM（ChatOpenAI(model="gpt-4.1")）结合对话上下文与 CopilotKit 状态中的 catalog 能力，通过结构化工具调用 render_a2ui 现场生成 A2UI v0.9 组件数组（root 组件 id 必须为 "root"），再包装为 a2ui_operations 返回。文件中的 [A2UI-DEBUG] 打印可帮助理解其调用时序：读取历史消息 → 拼接 context → 调用二级 LLM → 组装 surface/components/data。

数据查询工具

agent/src/query.py 在模块加载时就把 db.csv（agent/src/db.csv）读入内存缓存，工具 query_data 接收自然语言查询并返回整份缓存数据，供图表类前端组件（见 src/components/generative-ui/charts/）使用。注释说明提前缓存是为了规避 LangGraph Cloud 沙箱环境的文件 I/O 限制。

Docker 部署：容器化前后端

仓库提供了完整容器化方案（根目录 Dockerfile 与 docker/ 下的 Dockerfile.agent、Dockerfile.app，以及 docker-compose.test.yml）：

• Agent 镜像：安装 Python 依赖并启动 main.py（可参考 entrypoint.sh）；
• App 镜像：以 output: "standalone" 模式构建 Next.js（见 next.config.ts），并利用 docker-route-override.ts 替换路由实现——Docker 场景下 Agent 同样通过 AG-UI 提供服务（因为 langgraph-cli dev 需要 Docker-in-Docker，容器内不便运行），因此使用 @ag-ui/client 的 HttpAgent 直连 AGENT_URL；
• 环境变量：容器内通过 AGENT_URL（默认 http://localhost:8123）连接 Agent；CPK_INTELLIGENCE_API_KEY 存在时会启用 CopilotKit Intelligence（线程历史）并注入 identifyUser 用户标识，同时把 NEXT_PUBLIC_COPILOTKIT_THREADS_ENABLED 置为 "true" 打开线程抽屉入口；未配置时则回退到 InMemoryAgentRunner（内存会话）。

next.config.ts 中 serverExternalPackages: ["@copilotkit/runtime"] 用于在 standalone 输出中正确打包运行时；typescript.ignoreBuildErrors: true 则是为了容忍路由覆盖文件的类型差异（文件中均有注释说明）。

常见问题排查（Troubleshooting）

原 README 的排错经验结合源码进一步展开如下：

Agent 连接不上 / 提示"无法连接到工具"

1. 确认 Agent 端口：当前示例 Agent 默认监听 8123（由 agent/main.py 的 PORT 环境变量控制），前端 AGENT_URL 默认值也是 http://localhost:8123。注意原 README 排错章节提到的 8000 是模板遗留信息，请以 8123 为准。
2. 确认 API Key：OPENAI_API_KEY 必须存在于 agent/.env 或项目根 .env，且加载必须在 import src.agent 之前完成（见 agent/main.py 顶部逻辑）。
3. 确认两个服务均已启动：npm run dev 应同时出现 ui（蓝色前缀）与 agent（绿色前缀）两个 concurrently 进程；也可直接访问 http://localhost:8123/health 验证 Agent 存活。

Python 依赖 / 导入报错

• 优先使用 npm run install:agent（等价 cd agent && uv sync），它会依据 uv.lock 还原锁定的依赖版本；
• 若使用 Poetry 管理，README 提供的补救命令为：

cd agent
poetry lock && poetry install

• 检查 Python 版本 ≥ 3.12（pyproject.toml 的硬性要求），并确认 copilotkit、ag-ui-langgraph 等包成功安装。

如何基于此 Starter 扩展

README 明确说明该 Starter 设计为易于扩展，结合源码可以这样入手：

1. 改主题与样式：编辑 src/app/page.tsx、globals.css 与 page.module.css；
2. 新增工具：在 agent/src/ 下仿照 todos.py / query.py 编写 @tool，在 agent/src/agent.py 的 tools=[...] 中注册，如需前端实时状态流式同步，仿照 StateStreamingMiddleware 增加 StateItem 配置；
3. 新增 A2UI 组件：沿用固定 schema 模式（新增 JSON schema + a2ui.render）或动态生成模式（二级 LLM），前端在 src/components/generative-ui/ 中编写对应渲染器；
4. 接入外部 MCP：在 route.ts 的 mcpApps 中追加 server（默认已配置 Excalidraw MCP 示例）；
5. 多用户线程：正式部署前，务必把 identifyUser 的 "demo-user" 字面量替换为真实鉴权身份（代码注释明确提醒，否则所有用户共享同一线程历史）。

小结

langgraph-fastapi 示例回答了 CopilotKit 集成栈中一个高频问题：当 LangGraph Agent 跑在自托管 FastAPI 服务上时，如何以标准 AG-UI 协议接入 CopilotKit 前端。通过 ag-ui-langgraph 挂载端点、@copilotkit/runtime 的 HttpAgent 桥接、以及 A2UI 生成式 UI 机制，你可以在不依赖 LangGraph Platform 的前提下获得完整的"对话 + 富 UI 画布"体验。文中所有脚本、配置与代码均来自仓库当前实际文件，可直接按步骤复现，并在此基础上构建你自己的生产级 Agent 应用。

【免费下载链接】CopilotKit The Frontend Stack for Agents & Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol 项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit