Agent Chat UI：给 LangGraph 代理套一个聊天气泡，但要先想清楚生产模式

它如何工作：从表单到流式消息的路径

当你打开应用，首先看到的是一个设置表单。你需要填写三个关键值：Deployment URL，即 LangGraph 服务器的地址；Assistant/Graph ID，用于指定要对话的图或助手；还有 LangSmith API Key，但只在连接已部署的 LangGraph 服务器时需要。这个表单背后是环境变量的映射，NEXT_PUBLIC_API_URL 对应部署地址，NEXT_PUBLIC_ASSISTANT_ID 对应助手 ID，NEXT_PUBLIC_AUTH_SCHEME 对应认证方式。如果你设置了这些变量，应用会跳过表单直接进入聊天界面。聊天界面本身通过 LangGraph 的流式事件来渲染消息，具体来说是监听 on_chat_model_stream 事件，这样 LLM 的输出可以逐字显示。这里有一个细节值得注意：默认情况下，应用是直接从客户端连接 LangGraph 服务器的，这意味着每个用户都需要自己的 LangSmith API Key。这在本地开发没问题，但一旦部署到公网，就会变成安全漏洞。

两条消息隐藏的路径，机制完全不同

文档花了大量篇幅解释如何控制消息的可见性，这暗示了聊天界面与代理内部逻辑之间需要精细协调。第一种方式是防止实时流式显示，做法是给聊天模型加上 langsmith:nostream 标签。这个标签会阻止 on_chat_model_stream 事件被发出，所以消息不会在生成过程中逐字出现。但要注意，消息在 LLM 调用完成后，如果被保存到图的状态且未被进一步修改，它仍然会出现在界面上。第二种方式是永久隐藏，做法是在消息的 id 字段前加上 do-not-render- 前缀，同时给模型配置加上 langsmith:do-not-render 标签。UI 会显式过滤掉任何 id 以此前缀开头的消息。这两种方式解决不同的问题：前者适合你只想减少流式刷新的噪音，但最终还是要显示结果的场景；后者适合你根本不想让用户看到某条中间消息，比如工具调用的原始输出。你需要根据代理的逻辑决定用哪一种。

安装与启动：npx 命令和本地开发配置

安装过程相当直接。你可以用 npx create-agent-chat-app 来初始化一个新项目，或者 git clone 仓库后手动安装。如果你选择克隆，命令是 git clone https://github.com/langchain-ai/agent-chat-ui.git，然后 cd 进入目录，执行 pnpm install 安装依赖，最后 pnpm dev 启动开发服务器，默认地址是 http://localhost:3000。启动后，如果没有设置环境变量，你会看到设置表单。要绕过表单，可以复制 .env.example 为 .env，然后填入三个值。例如，如果你本地跑了一个 LangGraph 服务器在 2024 端口，助手 ID 是 agent，那么 .env 文件应该包含 NEXT_PUBLIC_API_URL=http://localhost:2024，NEXT_PUBLIC_ASSISTANT_ID=agent，NEXT_PUBLIC_AUTH_SCHEME=（留空）。如果你连接的是 LangSmith Agent Builder 部署，需要把 NEXT_PUBLIC_AUTH_SCHEME 设为 langsmith-api-key。修改 .env 后必须重启应用才能生效。整个过程没有复杂的构建步骤，但这意味着你必须预先准备好一个可访问的 LangGraph 服务，否则界面只是空壳。

生产部署的硬伤：客户端直连不可行

文档明确警告，默认的客户端直连模式不能用于生产环境。原因是它要求每个用户都拥有自己的 LangSmith API Key，并且自己配置 LangGraph 参数，这显然不现实。项目给出的解决方案是使用一个名为 langgraph-nextjs-api-passthrough 的包，或者自己实现代理。这个包的作用是在 Next.js 服务器端代理请求到 LangGraph 服务器，并把你的 LangSmith API Key 附加在请求上，这样用户就不需要任何密钥。这个设计选择是一个明显的权衡：它把认证逻辑从客户端移到了服务器，增加了部署的复杂度，但换来了安全性。如果你不想依赖这个第三方包，你需要自己写代理逻辑，这会增加维护成本。此外，文档没有提到如何管理多个用户的会话隔离，也没有讨论速率限制或审计日志，这些在生产环境中都是必须考虑的。所以，Agent Chat UI 适合原型验证，但生产化需要额外的工程投入。

Artifact 渲染：一个实用的扩展点

除了纯文本聊天，Agent Chat UI 还支持渲染工件，即附加在消息旁边的结构化内容。工件显示在聊天右侧的面板中。要使用这个功能，你需要从 thread.meta.artifact 字段获取工件上下文。README 提供了一个 useArtifact 钩子的示例，它返回一个包含 open 状态、setOpen 函数和 context 的元组。然后你可以用这个钩子渲染一个 Artifact 组件，比如一个可点击的卡片，点击后展开详细内容。这个机制的价值在于，它让代理不仅能返回文本，还能返回格式化的 UI 组件，比如代码编辑器、图表或表单。但这里有一个隐含要求：你的 LangGraph 服务必须在 thread 的 meta 中提供 artifact 字段，否则这个钩子会返回 undefined。这意味着工件支持需要你的代理端配合，不是开箱即用的。对于只想快速测试代理输出的用户来说，这个功能可能多余，但对于构建复杂助手界面的团队来说，它是一个值得探索的入口。

维护成本与许可证：MIT 下的双刃剑

这个项目使用 MIT 许可证，这意味着你可以自由使用、修改和分发，甚至闭源商用，但需要保留版权声明。从维护角度看，项目由 LangChain 团队维护，这保证了与 LangGraph 的兼容性会持续跟进，但也意味着你受制于他们的发布节奏。仓库没有列出任何正式版本，也没有发布记录，这暗示项目可能还在早期阶段，API 可能随时变化。例如，环境变量的命名、消息过滤的标签约定，这些都是实现细节，未来版本可能会调整。如果你在生产环境中依赖这些约定，你需要密切关注仓库的更新。另一个维护成本点是，项目依赖 pnpm 作为包管理器，如果你团队用的是 npm 或 yarn，需要额外安装 pnpm。最后，文档明确提到部署站点 agentchat.vercel.app，这意味着你可以直接使用托管版本而不需要自己部署，但如果你要定制界面或认证逻辑，你仍然需要自己维护一个实例。

替代方案：LangGraph Studio 与自建界面

如果你不想用 Agent Chat UI，最直接的替代是 LangGraph Studio，它是 LangChain 提供的桌面应用，用于可视化和调试 LangGraph 代理。LangGraph Studio 更专注于开发调试，提供状态查看、节点追踪等功能，而 Agent Chat UI 则是一个面向最终用户的聊天界面。两者的定位不同：前者是开发工具，后者是用户界面。另一个替代方案是自建聊天界面，使用 LangGraph 的 JavaScript 客户端直接调用 API，并用任意前端框架如 React 或 Vue 实现聊天逻辑。这样做的好处是你可以完全控制消息渲染、认证和部署，但代价是需要自己处理流式事件、消息状态管理和错误处理，这些 Agent Chat UI 已经帮你做好了。如果你需要深度定制，比如嵌入到现有产品中，或者需要支持多模态消息，自建可能更合适。但如果你的需求就是快速让用户与代理对话，Agent Chat UI 的开箱即用特性很难被击败。

编辑结论

Agent Chat UI 适合以下人群：已经有一个 LangGraph 服务，并且希望快速获得一个可交互的聊天界面，无论是本地调试还是部署到 Vercel。它不适合那些需要深度定制聊天逻辑或不想依赖 LangChain 生态的用户。在采用之前，你需要先确认你的 LangGraph 服务是否返回 messages 键，以及你是否愿意接受生产模式下必须使用 API Passthrough 或自定义代理的额外工作。对于 Agent Builder 部署，记得设置 NEXT_PUBLIC_AUTH_SCHEME=langsmith-api-key。如果你只是想试试，直接访问 agentchat.vercel.app 即可，但若要投入生产，请先阅读 Going to Production 一节，并决定你的认证方案。

官方来源

1. Issues
2. langchain-ai/agent-chat-ui on GitHub
3. License: MIT
4. Project website
5. README