1. 项目概述一个为LangGraph智能体量身打造的聊天界面如果你正在开发基于LangGraph的智能体应用无论是用Python还是TypeScript那么你很可能面临一个共同的“最后一公里”问题如何让最终用户或者仅仅是团队内部的测试人员能够方便、直观地与你的智能体进行对话总不能每次都让他们去跑Python脚本或者调用curl命令吧。这就是agent-chat-ui这个项目诞生的初衷。它是一个开箱即用的Next.js Web应用核心功能就是提供一个干净、现代的聊天界面让你能通过浏览器直接与任何暴露了标准messages接口的LangGraph服务器进行交互。简单来说它把后端复杂的LangGraph智能体逻辑包装成了一个类似ChatGPT的前端聊天窗口。这对于快速演示、内部测试、甚至构建面向用户的AI产品原型都至关重要。想象一下你花了一周时间精心设计了一个旅行规划智能体它的逻辑再强大如果交互方式停留在命令行也很难获得产品经理或客户的认可。agent-chat-ui正是填补了这个空白让你能专注于智能体本身的能力建设而将交互界面的问题交给一个成熟、可定制的解决方案。2. 核心设计思路与架构解析2.1 为什么选择Next.js与流式响应agent-chat-ui选择Next.js作为技术栈是一个经过深思熟虑的决定。Next.js不仅提供了强大的React开发体验和服务器端渲染能力其App Router架构对构建需要处理实时数据流的应用如聊天特别友好。智能体的响应往往是流式的LLM大语言模型会一个字一个字地生成内容Next.js的RSCReact Server Components和流式传输支持可以很好地处理这种场景实现消息的实时、无缝渲染避免用户长时间等待一个完整的响应。更重要的是这个项目的定位是一个“通用前端壳”。它不关心你的LangGraph智能体背后用的是OpenAI、Anthropic还是本地模型也不关心你的业务逻辑是处理PDF、查询数据库还是调用API。它只定义了一个清晰的契约后端需要提供一个能接收和返回messages数组的HTTP端点。这种高度解耦的设计使得它具备了极强的通用性无论是连接本地开发服务器还是连接部署在LangSmith平台上的生产环境智能体都能通过简单的配置完成。2.2 连接模式从开发到生产的演进路径项目的连接设计清晰地反映了从开发到生产的不同阶段需求这是我非常欣赏的一点。它没有假设一种“万能”的连接方式而是提供了清晰的路径。开发阶段直连模式在本地开发时最简单的方式就是让前端直接连接本地运行的LangGraph后端服务器例如http://localhost:2024。这时前端需要知道后端的URL和智能体ID。为了安全通常还需要开发者的LangSmith API Key来进行认证。agent-chat-ui初始的配置表单正是为这种模式设计的它让快速启动和测试变得极其简单。生产阶段代理模式与认证升级然而直连模式在生产环境中是行不通的。你不可能要求每个网站访客都拥有并配置自己的LangSmith API Key。因此项目提供了两种生产化方案API透传API Passthrough这是官方推荐的“快速通道”。它在你的Next.js应用服务器端建立一个代理API路由。前端不再直接调用LangGraph服务器而是调用自己的Next.js服务器接口然后由服务器端“透传”这个请求到真正的LangGraph服务器并在此过程中注入服务器端保存的、统一的LangSmith API Key。这样前端无需感知任何密钥所有认证和安全逻辑都收拢到了服务端。自定义认证Custom Authentication这是更高级、更灵活的方案。它要求你在部署LangGraph智能体时配置自己的认证机制例如JWT令牌。然后你的前端应用通过自己的认证系统如OAuth获取访问令牌并在请求LangGraph时携带该令牌。这种方式完全解耦了对LangSmith平台的依赖适合深度集成的企业级应用。这种设计体现了良好的工程实践为简单场景提供快捷方式为复杂需求保留扩展性。3. 从零开始本地运行与初体验3.1 环境准备与项目启动让我们抛开文档从实际操作者的角度走一遍流程。首先你需要一个Node.js环境建议18.x或以上版本。agent-chat-ui使用pnpm作为包管理器它的速度比npm快不少如果你还没安装可以先用npm装一个npm install -g pnpm。获取项目代码有两种官方推荐的方式我个人更推荐第一种因为它更“傻瓜式”npx create-agent-chat-app运行这个命令它会自动处理克隆仓库、安装依赖等一系列操作最终在当前目录生成一个可直接运行的项目。这是最快上手的方式。如果你想更深入地控制或者需要基于源码进行二次开发那就用传统的Git方式git clone https://github.com/langchain-ai/agent-chat-ui.git cd agent-chat-ui pnpm install安装依赖的过程可能会花点时间因为它需要下载Next.js、React、UI组件库等一系列包。依赖安装完成后运行开发服务器的命令非常标准pnpm dev此时打开浏览器访问http://localhost:3000你应该能看到一个简洁的配置页面而不是直接的聊天窗口。这是对的因为它需要你先告诉它你要连接谁。3.2 首次连接配置详解第一次打开的配置表单包含几个关键字段每一个都不能填错Deployment URL这是你的LangGraph服务器的地址。在本地开发时这通常就是你后端服务运行的地址和端口。例如如果你按照LangGraph的Python教程运行了一个本地智能体它很可能在http://localhost:2024上监听。这里填这个地址就行。Assistant/Graph ID这是智能体的标识符。当你用LangGraph定义智能体时通常会给它起一个名字比如travel_agent或customer_support。这个ID就是用来在服务器上定位你要对话的那个特定智能体。如果你不确定通常可以去查看你启动后端服务时的命令或配置文件。LangSmith API Key注意这个字段仅在连接已部署到LangSmith云端的生产服务器时才需要如果你连接的是本地服务器localhost这个字段应该留空。很多新手在这里会困惑去LangSmith官网生成一个Key填进去结果导致连接失败。本地开发时认证通常是通过其他方式如本地环境变量处理的前端不需要传这个Key。Built with Agent Builder这是一个复选框。如果你使用的LangGraph部署是通过LangSmith平台的“Agent Builder”可视化工具创建的那么你需要勾选这个选项。它会自动帮你设置正确的认证模式auth_scheme。对于纯代码部署的智能体通常不需要勾选。填好之后点击“Continue”如果一切配置正确页面会跳转到真正的聊天界面。你可以尝试发送一句“Hello”如果后端智能体正常运行你应该能看到它的回复。实操心得本地连接失败的常见排查点第一次连接失败太常见了。别慌按这个顺序检查后端服务是否在运行确保你的LangGraph服务器进程比如那个Python脚本正在运行并且没有报错退出。端口是否正确确认Deployment URL中的端口号如2024和你的后端服务监听的端口完全一致。CORS问题这是本地开发最常见的“拦路虎”。你的本地前端localhost:3000向本地后端localhost:2024发请求属于跨域请求。你需要在LangGraph后端服务器代码中启用CORS。对于Python的FastAPI通常需要添加类似app.add_middleware(CORSMiddleware, allow_origins[http://localhost:3000], allow_credentialsTrue, allow_methods[*], allow_headers[*])的中间件。智能体ID是否存在确认你填写的Assistant/Graph ID在后端有正确定义。有时可能是大小写敏感或拼写错误。4. 进阶配置环境变量与无缝启动每次打开都填一遍表单太麻烦了尤其是团队内部测试时。agent-chat-ui提供了通过环境变量预配置的方式让你可以直接进入聊天界面。4.1 环境变量配置实战在项目根目录你会发现一个.env.example文件。把它复制一份并重命名为.envcp .env.example .env然后打开.env文件你会看到类似下面的内容NEXT_PUBLIC_API_URLhttp://localhost:2024 NEXT_PUBLIC_ASSISTANT_IDagent NEXT_PUBLIC_AUTH_SCHEME # LANGSMITH_API_KEYyour_key_here # 通常不需要你需要根据你的实际情况修改NEXT_PUBLIC_API_URL和表单里的Deployment URL一样填你的LangGraph服务器地址。NEXT_PUBLIC_ASSISTANT_ID和表单里的Assistant/Graph ID一样。NEXT_PUBLIC_AUTH_SCHEME大多数情况下留空即可。只有当你连接的是LangSmith Agent Builder创建的部署并且没有使用API透传模式时才需要设置为langsmith-api-key。LANGSMITH_API_KEY这一行默认是注释掉的。对于本地开发保持注释。只有在你使用API透传模式连接生产环境时才需要取消注释并填写且这个Key应该保存在服务器端而不是前端环境变量里这里只是示例。重要安全提示以NEXT_PUBLIC_开头的变量会被打包到前端JavaScript代码中意味着任何访问你网页的人都能通过浏览器开发者工具看到它们。因此绝对不要将任何敏感信息如真正的API密钥、数据库密码放在NEXT_PUBLIC_变量里LANGSMITH_API_KEY在示例中之所以没有NEXT_PUBLIC_前缀就是因为它是一个需要保密的密钥。在生产环境中它应该通过服务器端环境变量或密钥管理服务来加载。修改完.env文件后需要重启你的Next.js开发服务器pnpm dev。再次访问localhost:3000你会发现它跳过了配置表单直接进入了聊天界面。这大大提升了开发调试的效率。4.2 多环境管理技巧在实际项目中你可能有开发、测试、生产多个环境。我建议使用不同的.env文件来管理.env.development本地开发配置指向localhost。.env.staging测试环境配置指向测试服务器。.env.production生产环境配置指向线上域名。Next.js会根据NODE_ENV环境变量自动加载对应的文件如npm run dev时加载.env.development。你也可以使用dotenv-cli等工具来指定加载哪个文件例如dotenv -e .env.staging -- pnpm dev。5. 深度定制控制消息流与渲染侧边栏5.1 精细控制聊天消息的显示一个成熟的智能体应用并非所有后端生成的消息都适合直接展示给用户。例如智能体在思考过程中调用一个“计算器工具”来演算这个工具调用的输入输出日志可能对调试有用但给用户看只会造成干扰。agent-chat-ui提供了两种级别的消息隐藏机制非常实用。场景一仅隐藏流式传输过程有时你希望LLM思考的“中间过程”不要一个字一个字地流式显示出来但最终完整的思考结果消息可以出现在聊天历史里。这可以通过给聊天模型添加一个特定的标签来实现。# Python (LangChain) 示例 from langchain_anthropic import ChatAnthropic model ChatAnthropic(modelclaude-3-haiku-20240307).with_config( config{tags: [langsmith:nostream]} )// TypeScript (LangChain.js) 示例 import { ChatAnthropic } from langchain/anthropic; const model new ChatAnthropic({ model: claude-3-haiku-20240307, }).withConfig({ tags: [langsmith:nostream] });这样配置后当这个模型产生响应时前端将不会收到流式更新的事件用户看不到“正在输入...”的跳动效果直到该LLM调用完全结束最终生成的消息才会一次性添加到聊天记录中。这适用于那些不需要实时反馈、但结果重要的步骤。场景二永久隐藏消息如果你有一些完全用于内部状态流转、绝对不想让用户看到的消息比如某些系统指令、临时数据结构就需要更彻底的方法。这需要同时做两件事给模型打上langsmith:do-not-render标签。在将该消息保存到Graph状态之前给消息的id字段加上do-not-render-前缀。# Python 示例 result model.invoke([human_message]) # 关键步骤在返回结果、存入状态前修改消息ID result.id fdo-not-render-{result.id} return {messages: [result]} # 这个消息将永远不会出现在UI中// TypeScript 示例 const result await model.invoke([humanMessage]); // 关键步骤在返回结果、存入状态前修改消息ID result.id do-not-render-${result.id}; return { messages: [result] }; // 这个消息将永远不会出现在UI中前端UI会显式过滤掉所有id以do-not-render-开头的消息。这是一种非常可靠的消息过滤机制。避坑指南这里有一个常见的误解顺序。标签langsmith:do-not-render是打在模型调用的配置上用于告诉LangSmith的追踪系统“这个调用产生的消息可能不需要渲染”。而修改id前缀是在消息对象被产出后、存入状态前进行的这是给前端UI的明确指令。两者配合缺一不可。只打标签不改ID消息最终可能还是会显示出来只改ID不打标签在LangSmith的追踪视图中可能无法正确归类。5.2 渲染富内容侧边栏Artifact实战聊天窗口只能显示文本但智能体的输出可能是丰富的一张生成的图片、一个结构化表格、一段代码、甚至是一个可交互的图表。agent-chat-ui通过“Artifact”工件的概念和侧边栏机制来支持这种富内容渲染。其核心思想是智能体在运行过程中可以将一段数据上下文和一个React组件“绑定”起来推送到前端。前端通过一个特殊的HookuseArtifact获取到这个“绑定”并在用户触发某些操作如点击一个卡片时在侧边栏中渲染该组件并将数据传递给它。后端如何发送Artifact这通常是在你的LangGraph智能体定义中完成的。你需要修改状态使其包含一个特殊的meta字段或利用线程元数据里面存放Artifact的上下文。具体格式需要参考LangGraph关于自定义元数据的文档但大体思路是构造一个包含组件标识和上下文数据的对象。前端如何接收与渲染项目提供了一个useArtifact的工具Hook。使用起来就像下面这样// 假设我们有一个“报告生成器”智能体它生成了一个Markdown格式的报告 import { useArtifact } from /utils/use-artifact; import ReactMarkdown from react-markdown; export function ReportViewer({ reportId }) { // 使用Hook获取Artifact。泛型{content: string}指定了上下文数据的类型 const [Artifact, { open, setOpen, context }] useArtifact{content: string, title: string}(); // 假设我们从某个事件或状态中知道当前该显示哪个报告 const currentReport findReportById(reportId); return ( div {/* 一个可点击的摘要卡片 */} div classNamep-4 border rounded-lg shadow-sm cursor-pointer hover:bg-gray-50 onClick{() { // 点击时设置要传递给侧边栏组件的数据上下文并打开侧边栏 // 这里的setContext和setOpen来自useArtifact返回的bag setContext({ content: currentReport.markdown, title: currentReport.name }); setOpen(true); }} h3 classNamefont-semibold{currentReport.name}/h3 p classNametext-sm text-gray-600点击查看详细报告/p /div {/* Artifact侧边栏组件。 当open为true且context有值时这个组件会被渲染在页面侧边栏。 title和children会作为props传递给这个组件 */} Artifact title{context?.title || 报告详情} {context?.content ? ( div classNamep-6 prose max-w-none ReactMarkdown{context.content}/ReactMarkdown /div ) : ( p暂无内容/p )} /Artifact /div ); }这个模式非常强大它将聊天的主流程文本对话和辅助的富内容展示侧边栏解耦了。智能体可以专注于生成高质量的数据和内容而前端则负责以最合适的方式呈现它。6. 生产部署指南安全与性能考量将agent-chat-ui投入生产环境远不止是把它部署到Vercel或Netlify那么简单。核心挑战在于身份认证、安全性和架构。直接让浏览器里的JavaScript拿着用户的LangSmith API Key去调用你的智能体这在生产环境中是不可接受的。6.1 方案一API透传推荐给大多数场景这是官方提供的最简单、最安全的生产化方案。其原理如下图所示此处用文字描述用户在前端聊天窗口发送消息。前端不是直接发给LANGGRAPH_API_URL而是发给自己的Next.js应用的一个API路由例如/api/chat。这个Next.js API路由运行在服务器端Serverless Function或Server它接收到请求后在服务器端环境读取安全保存的LANGSMITH_API_KEY。服务器端代理将请求转发到真正的LangGraph生产服务器并在请求头中注入Authorization: Bearer LANGSMITH_API_KEY。将LangGraph服务器的响应原样返回给前端。这样敏感的API Key完全不会暴露给前端。agent-chat-ui项目已经内置了对这个模式的支持。你需要做的配置如下环境变量配置在部署平台如Vercel的项目设置中配置NEXT_PUBLIC_API_URLhttps://你的域名.com/api # 指向你自己的Next.js应用的API路由 NEXT_PUBLIC_ASSISTANT_ID你的智能体ID LANGGRAPH_API_URLhttps://你的智能体.deployment.langchain.app # 你的LangGraph生产服务器地址 LANGSMITH_API_KEYlsv2_你的密钥 # 在这里安全地配置你的密钥代码层面项目已经包含了/app/api/[...path]/route.ts文件它使用了langgraph-nextjs-api-passthrough包。只要你正确配置了环境变量这个路由就会自动工作将/api/*的请求代理到LANGGRAPH_API_URL。部署注意事项使用Vercel部署时确保你的环境变量正确设置。NEXT_PUBLIC_*变量会在构建时被内联所以如果你更改了它们需要重新部署。而非公开的变量如LANGSMITH_API_KEY则在运行时被Serverless Function读取。另外注意Vercel的Serverless Function有超时限制默认10秒如果你的智能体响应时间很长可能需要调整maxDuration配置或考虑流式响应以保持连接。6.2 方案二自定义认证适合企业级集成如果你的应用已经有自己的用户系统如OAuth2、JWT并且希望智能体的访问权限与你现有的用户体系打通那么就需要在LangGraph部署端设置自定义认证并修改前端以传递自定义令牌。后端LangGraph部署你需要按照LangGraph官方文档为你的部署配置自定义认证逻辑。例如你可以设置只接受带有特定JWT令牌的请求并在令牌中解析用户身份和权限。前端Agent Chat UI你需要修改前端代码在调用useTypedStream这个核心Hook时传递自定义的请求头。// 假设你从自己的AuthProvider中获取到了访问令牌 const { getAccessToken } useAuth(); const streamValue useTypedStream({ apiUrl: process.env.NEXT_PUBLIC_API_URL, // 这里直接指向你的LangGraph生产地址 assistantId: process.env.NEXT_PUBLIC_ASSISTANT_ID, // ... 其他配置 defaultHeaders: { // 注入你的自定义认证头 Authorization: Bearer ${getAccessToken()}, }, });同时你需要确保你的NEXT_PUBLIC_API_URL直接指向配置了自定义认证的LangGraph服务器地址并且NEXT_PUBLIC_AUTH_SCHEME设置为空或相应的值。这种方案给了你最大的控制权可以实现基于角色的访问控制RBAC、速率限制、审计日志等高级功能但实现复杂度也最高。7. 常见问题排查与性能优化7.1 连接与通信问题速查表问题现象可能原因排查步骤点击“Continue”后长时间无反应或报错1. 后端服务未启动或崩溃。2. CORS策略阻止请求。3. 网络问题防火墙、代理。1. 检查后端进程是否运行查看日志。2. 打开浏览器开发者工具“网络”选项卡查看请求是否被阻塞并报CORS错误。在后端服务中正确配置CORS头。3. 尝试用curl或Postman直接调用后端URL看是否通。连接成功但发送消息后无回复1. 智能体ID (assistant_id) 错误。2. 后端智能体逻辑有bug或超时。3. 认证失败生产环境。1. 确认填写的ID与后端定义的完全一致。2. 查看后端服务日志确认请求是否收到智能体是否开始处理有无报错。3. 生产环境下检查API Key或自定义令牌是否有效、有无过期。消息显示“正在输入...”但永远不完成1. 后端流式响应中断。2. 前端处理流的逻辑卡住。3. 网络连接不稳定。1. 这是最难排查的。首先查看后端日志确认智能体是否完整执行完毕并关闭了响应流。2. 在前端代码中useTypedStream附近添加日志看是否收到了done事件。3. 检查服务器和浏览器控制台有无错误。生产环境部署后白屏或4041. Next.js构建或路由配置问题。2. 环境变量未正确加载。3. API代理路由配置错误。1. 检查部署日志确认构建成功。访问/api/health等端点测试API路由是否存活。2. 在部署平台的控制台确认环境变量已设置且值正确注意空格和换行。3. 确认NEXT_PUBLIC_API_URL指向了正确的、包含/api路径的地址。7.2 性能与体验优化建议启用流式响应确保你的LangGraph智能体配置为返回流式响应。这能极大提升用户体验用户可以看到消息逐字生成而不是等待一个漫长的完整响应。在LangChain中这通常意味着使用astream或astream_events而不是ainvoke。前端加载状态agent-chat-ui自带基本的加载状态。但你可以进一步优化比如在发送消息时禁用输入框、添加发送中的动画提示避免用户重复发送。错误处理与重试网络请求可能失败。在前端代码中可以考虑为useTypedStream添加错误边界Error Boundary或重试逻辑。当连接中断或服务器返回5xx错误时给用户一个友好的提示并提供“重试”按钮。对话历史管理对于长对话智能体的上下文窗口可能有限。可以考虑在前端实现“新对话”按钮其本质是清空前端消息状态并向后端发起一个创建新线程的请求。这比让用户刷新页面体验更好。部署平台选择如果你使用API透传模式你的Next.js应用将同时承担前端服务和后端代理的角色。选择像Vercel这样的平台能获得最好的兼容性。如果部署在其他平台请确保其Node.js版本支持Next.js的App Router和Serverless Functions。这个项目作为一个桥梁极大地简化了LangGraph智能体与用户之间的交互。它的价值在于其“通用性”和“可定制性”。你可以把它当作一个快速原型工具也可以基于它的代码进行深度定制打造出完全符合你品牌和业务需求的AI对话界面。理解其连接机制、消息控制方法和生产部署路径是将其成功应用于实际项目的关键。