如何安装并运行 awesome-llm-apps 的 Generative UI Starter Project：一个聊天与 Agent 共享状态的看板

这篇文章解决的是：在本地把 awesome-llm-apps 仓库中 generative_ui_agents/generative-ui-starter-project 这个项目装起来并跑通。它是一个聊天驱动的看板（To Do / Done 两列），看板的任务列表状态存放在 LangGraph Agent 端，通过 CopilotKit 的 useAgent() 与 React 前端双向同步——Agent 通过工具调用移动卡片，你在界面里点击、编辑、排序，双方观察的是同一份状态，没有独立的前端 store。

准备条件

按 README.md 的 Prerequisites 一节，需要：

• Node.js 18+
• Python 3.8+（注意：Agent 子项目 agent/pyproject.toml 声明 requires-python = ">=3.12"，agent/langgraph.json 中 python_version 固定为 3.12，uv 安装依赖时会按此解析）
• uv（Python 包管理器）
• npm（默认）、pnpm、yarn 或 bun 任选其一
• OpenAI API Key（LangGraph Agent 使用，Agent 在 agent/main.py 中通过 ChatOpenAI 调用 gpt-5.5 模型）

安装依赖

在项目目录下执行：

npm install

根据 README，这一步会通过 uv sync 一并安装 Python Agent 的依赖。对应 package.json 中的配置：postinstall 钩子会执行 install:agent 脚本，即 scripts/setup-agent.sh（Windows 下为 setup-agent.bat），其内容就是进入 agent/ 目录后运行 uv sync。

如果 Agent 依赖安装出问题，也可以单独重跑：

npm run install:agent

配置环境变量

复制示例环境文件并填入 OpenAI API Key：

cp .env.example .env

然后编辑 .env。.env.example 中预置了两项：

AGENT_URL=http://localhost:8123
OPENAI_API_KEY=your-openai-api-key-here

• OPENAI_API_KEY 替换为你自己的 Key。
• AGENT_URL 指向前端 CopilotKit API 路由连接 Agent 的地址。前端代码 src/app/api/copilotkit/[[...slug]]/route.ts 中按 AGENT_URL → LANGGRAPH_DEPLOYMENT_URL → http://localhost:8123 的顺序取值，本地开发保持默认值即可，不需要修改。

启动开发服务器

npm run dev

README 说明该命令会同时启动 UI 和 Agent 两个开发服务器。package.json 中 dev 用 concurrently 并行运行 dev:ui（next dev --turbopack）和 dev:agent（执行 scripts/run-agent.sh），其中 run-agent.sh 的内容是：

cd "$(dirname "$0")/../agent" || exit 1
npx @langchain/langgraph-cli dev --port 8123 --no-browser

即 Agent 通过 langgraph-cli 的 dev 模式跑在 8123 端口。各脚本用途（来自 README 的 Available Scripts，可用你偏好的包管理器执行）：

• dev — 同时启动 UI 和 Agent
• dev:debug — 带 LOG_LEVEL=debug 的调试日志启动
• dev:ui — 只启动 Next.js UI
• dev:agent — 只启动 LangGraph Agent
• build — 构建生产版本；start — 启动生产服务器

验证是否跑通

按 CLAUDE.md 的 Development 一节，两个服务的端口是：

• Next.js 前端：3000 端口（npm run dev:ui）
• LangGraph Agent：8123 端口（npm run dev:agent）

启动后浏览器打开 http://localhost:3000，应看到聊天窗口与看板画布并排布局（example-layout）。看板包含 To Do 和 Done 两列，卡片可点击、编辑、排序。

对 Agent 端，项目提供的 Docker 冒烟测试栈 docker-compose.test.yml 中的 healthcheck 给出了两个可参照的检查方式（注意该文件本身是 e2e 测试栈的配置，这里仅借用其检查路径）：

• Agent 健康检查：请求 http://localhost:8123/ok，返回 200 即视为 Agent 就绪（compose 中 interval: 5s、retries: 30、start_period: 30s）
• 前端健康检查：请求 http://localhost:3000/，状态码 200 即视为应用就绪

功能层面的验证是文档描述的核心行为：在聊天中让 Agent 管理任务，或在 UI 中勾选/编辑卡片，两边的变更应反映在同一个 agent.state.todos 上——前端读取 agent.state.todos，用户操作通过 agent.setState({ todos: ... }) 写回，Agent 通过 manage_todos 工具更新，前端自动重渲染（见 README.md 的 shared agent state 说明和 CLAUDE.md 的 How State Flows 一节）。

可选：用 Docker Compose 跑 e2e 冒烟测试

docker-compose.test.yml 提供了完整的测试栈，文件头注释写明用途是"与 aimock 做 e2e 冒烟测试"，命令为：

docker compose -f docker-compose.test.yml up -d

该栈会启动四个服务：aimock（用 fixtures/default.json 中的预置应答模拟 LLM，因此 Agent 使用 OPENAI_API_KEY=test-key-for-aimock 和指向 aimock 的 OPENAI_BASE_URL，不消耗真实 API）、agent（构建自 docker/Dockerfile.agent，以 langgraph dev 跑在 8123）、app（构建自 docker/Dockerfile.app，前端跑在 3000）、tests（Playwright 执行 starter-smoke 测试）。这是一个独立于本地 npm run dev 主路径的验证手段，不依赖真实 OpenAI Key。

边界与限制

• 本地开发主路径依赖真实 OpenAI API Key 与 gpt-5.5 模型，dev 脚本没有提供跳过 Key 的方式；不需要真实 Key 时使用上面的 aimock 测试栈。
• README 写的前置要求是 Python 3.8+，但 Agent 代码声明 requires-python >= 3.12，两处不一致以 Agent 侧声明为准：uv 依赖解析会按 3.12 处理（langgraph.json 中 python_version: "3.12"）。
• 项目同时内置了 A2UI 声明式生成式 UI（航班搜索固定 schema 与 generate_a2ui 动态 schema 两种模式，见 README 的 A2UI 一节）。它属于同一应用的附加能力，不影响安装与启动流程；showcase.json 当前值为 {"showcase":"opengenui"}，用于控制建议按钮高亮，README 说明 "showcase": "a2ui" 会高亮 A2UI 演示、"showcase": "default" 不高亮。
• 项目根目录另有生产镜像用的 Dockerfile 与 entrypoint.sh（在容器内用 serve.py 包装 Agent 走 AG-UI 协议，因为 langgraph-cli dev 需要 Docker-in-Docker）。那是部署场景，本地安装运行不需要。