尧图网页设计 
使用 LangGraph FastAPI CopilotKit 搭建 Agent 前端从零运行 langgraph-fastapi 集成示例【免费下载链接】CopilotKitThe 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.jsApp 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.js18仓库示例使用 Next.js 16.1.6见 package.json建议使用较新 LTSPython3.8README 说法实际 pyproject.toml 声明requires-python 3.12请以 3.12 为准Python 包管理器Poetry 2README 说法当前仓库实际使用uv存在 uv.lockinstall:agent脚本执行uv syncPoetry 仅保留在排错建议中前端包管理器npm / pnpm / yarn / bun 任选仓库默认 npmdev脚本依赖concurrently模型密钥OpenAI API KeyAgent 图使用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 安装如下关键依赖copilotkit0.1.96Python 侧 SDK提供LangGraphAGUIAgent、CopilotKitMiddleware、StateStreamingMiddleware与a2ui渲染工具langgraph1.1.6、langchain1.2.15、langchain-openai1.1.9Agent 运行时与模型接入ag-ui-langgraph[fastapi]0.0.43把 LangGraph 图包装成 AG-UI 协议端点含 FastAPI 扩展fastapi0.115.5,1.0.0、uvicorn0.29.0,1.0.0HTTP 服务ag-ui-protocol0.1.19AG-UI 协议类型定义。第 3 步配置 OpenAI API KeyREADME 给出的做法是写入agent/.envecho OPENAI_API_KEYyour-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 devdev脚本使用concurrently同时拉起两个进程见 package.jsondev:uinext dev --turbopack启动 Next.js 前端dev:agentcd agent uv run main.py启动 FastAPI agent 服务默认端口8123。启动后前端默认运行在 Next.js 开发端口通常为http://localhost:3000Agent 服务运行在http://localhost:8123Agent 服务还额外提供了GET /health健康检查端点见 agent/main.py。可用脚本一览以下脚本均可在examples/integrations/langgraph-fastapi目录下用你选择的包管理器执行脚本命令npm 示例作用devnpm run dev同时启动 UI 与 agent 两个开发服务器dev:debugnpm run dev:debug以LOG_LEVELdebug环境变量启动开发模式输出调试日志dev:uinpm run dev:ui仅启动 Next.js UInext dev --turbopackdev:agentnpm run dev:agent仅启动 LangGraph agent 服务cd agent uv run main.pybuildnpm run build构建 Next.js 生产包startnpm run start启动 Next.js 生产服务器install:agentnpm 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。它用LangGraphHttpAgent指向AGENT_URL默认http://localhost:8123/直接以 AG-UI 协议访问 FastAPI 服务用CopilotRuntime聚合 agents、开启openGenerativeUI: true、配置a2ui本例关闭工具自动注入injectA2UITool: false因为 Agent 侧已显式提供 A2UI 工具通过 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 图、状态流式与 A2UIFastAPI 入口与 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( appapp, agentLangGraphAGUIAgent( namesample_agent, descriptionAn example agent to use as a starting point for your own agent., graphgraph, ), path/, )即把src.agent中导出的graph包装成LangGraphAGUIAgent再通过add_langgraph_fastapi_endpoint挂载到根路径/对外即成为符合 AG-UI 协议的 Agent 端点。默认端口由环境变量PORT控制回退到8123。LangGraph 图工具、中间件与状态agent/src/agent.py 是图的定义处要点如下模型ChatOpenAI(modelgpt-5.4, model_kwargs{parallel_tool_calls: False})关闭并行工具调用保证 A2UI/状态类工具按顺序执行工具清单query_dataCSV 数据查询、todo_toolsTo-Do 管理、generate_a2ui动态 A2UI、search_flights固定 schema A2UI中间件CopilotKitMiddleware()负责 AG-UI 上下文注入StateStreamingMiddleware(StateItem(state_keytodos, toolmanage_todos, tool_argumenttodos))负责把manage_todos工具写入的todos字段实时流式同步给前端状态 schema使用AgentState继承 LangChain 的AgentState并扩展todos: list[Todo]字段见 agent/src/todos.pycheckpointer由于是 uvicorn ag-ui-langgraph方式运行非langgraph-cli dev自带 checkpointer图显式传入MemorySaver()用于进程内线程状态持久化系统提示词约束模型输出 1~2 句简洁回答并给出工具使用指引航班→search_flights仪表盘/富 UI→generate_a2ui图表→先query_dataTo-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负责渲染固定 schemaa2ui_fixed_schema.pysearch_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后自动渲染航班卡片。动态 schemaa2ui_dynamic_schema.pygenerate_a2ui用二级 LLMChatOpenAI(modelgpt-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.csvagent/src/db.csv读入内存缓存工具query_data接收自然语言查询并返回整份缓存数据供图表类前端组件见 src/components/generative-ui/charts/使用。注释说明提前缓存是为了规避 LangGraph Cloud 沙箱环境的文件 I/O 限制。Docker 部署容器化前后端仓库提供了完整容器化方案根目录 Dockerfile 与 docker/ 下的Dockerfile.agent、Dockerfile.app以及 docker-compose.test.ymlAgent 镜像安装 Python 依赖并启动main.py可参考 entrypoint.shApp 镜像以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连接 AgentCPK_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 连接不上 / 提示无法连接到工具确认 Agent 端口当前示例 Agent 默认监听8123由 agent/main.py 的PORT环境变量控制前端AGENT_URL默认值也是http://localhost:8123。注意原 README 排错章节提到的 8000 是模板遗留信息请以 8123 为准。确认 API KeyOPENAI_API_KEY必须存在于agent/.env或项目根.env且加载必须在import src.agent之前完成见 agent/main.py 顶部逻辑。确认两个服务均已启动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.12pyproject.toml 的硬性要求并确认copilotkit、ag-ui-langgraph等包成功安装。如何基于此 Starter 扩展README 明确说明该 Starter 设计为易于扩展结合源码可以这样入手改主题与样式编辑 src/app/page.tsx、globals.css 与 page.module.css新增工具在agent/src/下仿照todos.py/query.py编写tool在 agent/src/agent.py 的tools[...]中注册如需前端实时状态流式同步仿照StateStreamingMiddleware增加StateItem配置新增 A2UI 组件沿用固定 schema 模式新增 JSON schema a2ui.render或动态生成模式二级 LLM前端在 src/components/generative-ui/ 中编写对应渲染器接入外部 MCP在 route.ts 的mcpApps中追加 server默认已配置 Excalidraw MCP 示例多用户线程正式部署前务必把identifyUser的demo-user字面量替换为真实鉴权身份代码注释明确提醒否则所有用户共享同一线程历史。小结langgraph-fastapi示例回答了 CopilotKit 集成栈中一个高频问题当 LangGraph Agent 跑在自托管 FastAPI 服务上时如何以标准 AG-UI 协议接入 CopilotKit 前端。通过ag-ui-langgraph挂载端点、copilotkit/runtime的 HttpAgent 桥接、以及 A2UI 生成式 UI 机制你可以在不依赖 LangGraph Platform 的前提下获得完整的对话 富 UI 画布体验。文中所有脚本、配置与代码均来自仓库当前实际文件可直接按步骤复现并在此基础上构建你自己的生产级 Agent 应用。【免费下载链接】CopilotKitThe 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 LangGraph + FastAPI + CopilotKit 搭建 Agent 前端：从零运行 langgraph-fastapi 集成示例
使用 LangGraph FastAPI CopilotKit 搭建 Agent 前端从零运行 langgraph-fastapi 集成示例【免费下载链接】CopilotKitThe 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.jsApp 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.js18仓库示例使用 Next.js 16.1.6见 package.json建议使用较新 LTSPython3.8README 说法实际 pyproject.toml 声明requires-python 3.12请以 3.12 为准Python 包管理器Poetry 2README 说法当前仓库实际使用uv存在 uv.lockinstall:agent脚本执行uv syncPoetry 仅保留在排错建议中前端包管理器npm / pnpm / yarn / bun 任选仓库默认 npmdev脚本依赖concurrently模型密钥OpenAI API KeyAgent 图使用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 安装如下关键依赖copilotkit0.1.96Python 侧 SDK提供LangGraphAGUIAgent、CopilotKitMiddleware、StateStreamingMiddleware与a2ui渲染工具langgraph1.1.6、langchain1.2.15、langchain-openai1.1.9Agent 运行时与模型接入ag-ui-langgraph[fastapi]0.0.43把 LangGraph 图包装成 AG-UI 协议端点含 FastAPI 扩展fastapi0.115.5,1.0.0、uvicorn0.29.0,1.0.0HTTP 服务ag-ui-protocol0.1.19AG-UI 协议类型定义。第 3 步配置 OpenAI API KeyREADME 给出的做法是写入agent/.envecho OPENAI_API_KEYyour-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 devdev脚本使用concurrently同时拉起两个进程见 package.jsondev:uinext dev --turbopack启动 Next.js 前端dev:agentcd agent uv run main.py启动 FastAPI agent 服务默认端口8123。启动后前端默认运行在 Next.js 开发端口通常为http://localhost:3000Agent 服务运行在http://localhost:8123Agent 服务还额外提供了GET /health健康检查端点见 agent/main.py。可用脚本一览以下脚本均可在examples/integrations/langgraph-fastapi目录下用你选择的包管理器执行脚本命令npm 示例作用devnpm run dev同时启动 UI 与 agent 两个开发服务器dev:debugnpm run dev:debug以LOG_LEVELdebug环境变量启动开发模式输出调试日志dev:uinpm run dev:ui仅启动 Next.js UInext dev --turbopackdev:agentnpm run dev:agent仅启动 LangGraph agent 服务cd agent uv run main.pybuildnpm run build构建 Next.js 生产包startnpm run start启动 Next.js 生产服务器install:agentnpm 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。它用LangGraphHttpAgent指向AGENT_URL默认http://localhost:8123/直接以 AG-UI 协议访问 FastAPI 服务用CopilotRuntime聚合 agents、开启openGenerativeUI: true、配置a2ui本例关闭工具自动注入injectA2UITool: false因为 Agent 侧已显式提供 A2UI 工具通过 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 图、状态流式与 A2UIFastAPI 入口与 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( appapp, agentLangGraphAGUIAgent( namesample_agent, descriptionAn example agent to use as a starting point for your own agent., graphgraph, ), path/, )即把src.agent中导出的graph包装成LangGraphAGUIAgent再通过add_langgraph_fastapi_endpoint挂载到根路径/对外即成为符合 AG-UI 协议的 Agent 端点。默认端口由环境变量PORT控制回退到8123。LangGraph 图工具、中间件与状态agent/src/agent.py 是图的定义处要点如下模型ChatOpenAI(modelgpt-5.4, model_kwargs{parallel_tool_calls: False})关闭并行工具调用保证 A2UI/状态类工具按顺序执行工具清单query_dataCSV 数据查询、todo_toolsTo-Do 管理、generate_a2ui动态 A2UI、search_flights固定 schema A2UI中间件CopilotKitMiddleware()负责 AG-UI 上下文注入StateStreamingMiddleware(StateItem(state_keytodos, toolmanage_todos, tool_argumenttodos))负责把manage_todos工具写入的todos字段实时流式同步给前端状态 schema使用AgentState继承 LangChain 的AgentState并扩展todos: list[Todo]字段见 agent/src/todos.pycheckpointer由于是 uvicorn ag-ui-langgraph方式运行非langgraph-cli dev自带 checkpointer图显式传入MemorySaver()用于进程内线程状态持久化系统提示词约束模型输出 1~2 句简洁回答并给出工具使用指引航班→search_flights仪表盘/富 UI→generate_a2ui图表→先query_dataTo-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负责渲染固定 schemaa2ui_fixed_schema.pysearch_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后自动渲染航班卡片。动态 schemaa2ui_dynamic_schema.pygenerate_a2ui用二级 LLMChatOpenAI(modelgpt-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.csvagent/src/db.csv读入内存缓存工具query_data接收自然语言查询并返回整份缓存数据供图表类前端组件见 src/components/generative-ui/charts/使用。注释说明提前缓存是为了规避 LangGraph Cloud 沙箱环境的文件 I/O 限制。Docker 部署容器化前后端仓库提供了完整容器化方案根目录 Dockerfile 与 docker/ 下的Dockerfile.agent、Dockerfile.app以及 docker-compose.test.ymlAgent 镜像安装 Python 依赖并启动main.py可参考 entrypoint.shApp 镜像以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连接 AgentCPK_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 连接不上 / 提示无法连接到工具确认 Agent 端口当前示例 Agent 默认监听8123由 agent/main.py 的PORT环境变量控制前端AGENT_URL默认值也是http://localhost:8123。注意原 README 排错章节提到的 8000 是模板遗留信息请以 8123 为准。确认 API KeyOPENAI_API_KEY必须存在于agent/.env或项目根.env且加载必须在import src.agent之前完成见 agent/main.py 顶部逻辑。确认两个服务均已启动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.12pyproject.toml 的硬性要求并确认copilotkit、ag-ui-langgraph等包成功安装。如何基于此 Starter 扩展README 明确说明该 Starter 设计为易于扩展结合源码可以这样入手改主题与样式编辑 src/app/page.tsx、globals.css 与 page.module.css新增工具在agent/src/下仿照todos.py/query.py编写tool在 agent/src/agent.py 的tools[...]中注册如需前端实时状态流式同步仿照StateStreamingMiddleware增加StateItem配置新增 A2UI 组件沿用固定 schema 模式新增 JSON schema a2ui.render或动态生成模式二级 LLM前端在 src/components/generative-ui/ 中编写对应渲染器接入外部 MCP在 route.ts 的mcpApps中追加 server默认已配置 Excalidraw MCP 示例多用户线程正式部署前务必把identifyUser的demo-user字面量替换为真实鉴权身份代码注释明确提醒否则所有用户共享同一线程历史。小结langgraph-fastapi示例回答了 CopilotKit 集成栈中一个高频问题当 LangGraph Agent 跑在自托管 FastAPI 服务上时如何以标准 AG-UI 协议接入 CopilotKit 前端。通过ag-ui-langgraph挂载端点、copilotkit/runtime的 HttpAgent 桥接、以及 A2UI 生成式 UI 机制你可以在不依赖 LangGraph Platform 的前提下获得完整的对话 富 UI 画布体验。文中所有脚本、配置与代码均来自仓库当前实际文件可直接按步骤复现并在此基础上构建你自己的生产级 Agent 应用。【免费下载链接】CopilotKitThe 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考