给智能体套上华丽前端:lca-lc-foundations 附赠 Next.js Agent Chat UI 实战
给智能体套上华丽前端:lca-lc-foundations 附赠 Next.js Agent Chat UI 实战
学完 LangGraph 智能体后,最头疼的往往是"它只能跑在 Studio 里看"。好消息是:lca-lc-foundations 仓库在 Module 3 里附赠了一个基于 Next.js 的 Agent Chat UI,可以为任意 LangGraph 服务器套上一个流式聊天界面,几步就能在浏览器里和智能体对话 🎉
一、Agent Chat UI 是什么:给 LangGraph 智能体配一个聊天窗口
Agent Chat UI 是一个 Next.js 应用,核心能力一句话概括:只要你的 LangGraph 图的状态里带 messages 键,它就能通过聊天界面与之对话。
它的"娘家"位置就在课程仓库里:
- 前端应用:notebooks/module-3/agent-chat-ui/
- 配套演示智能体:notebooks/module-3/3.5_email_agent.py(一个会查收件箱、发邮件的 Email Assistant)
- 服务器声明:notebooks/module-3/langgraph.json(定义了名为
agent的图)
开箱即得的功能包括:
| 能力 | 说明 |
|---|---|
| ⚡ 流式渲染 | 基于 useStream 钩子实时显示模型输出与工具调用 |
| 🧵 会话管理 | 多会话(Thread)历史,可随时新建/切换 |
| 🙋 人工介入 | 原生支持 HITL 中断,可渲染审批/表单 |
| 📎 Artifact 侧栏 | 在聊天右侧弹出独立内容面板 |
| 🔒 生产代理 | 内置 API Passthrough 反向代理,密钥不出服务器 |
二、快速上手:3 步启动智能体聊天界面
第 1 步:启动 LangGraph 开发服务器
在 notebooks/module-3 目录下执行(前提已按 README.md 配好 .env 与虚拟环境):
uv run langgraph dev
langgraph.json 会把 agent 这个图注册到本地服务器(默认 http://localhost:2024)。
第 2 步:安装并启动前端
进入 UI 目录(需 Node.js 环境):
cd notebooks/module-3/agent-chat-ui
pnpm install
pnpm dev
应用将运行在 http://localhost:3000。
第 3 步:填写连接表单
打开页面后会提示输入三项信息:
- Deployment URL:LangGraph 服务器地址(开发环境填
http://localhost:2024) - Assistant/Graph ID:图或助手名称(本仓库示例为
agent) - LangSmith API Key:仅连接线上部署时需要
点击 Continue 即可开聊。💬
💡 跳过表单的小技巧:复制
.env.example为.env并设置NEXT_PUBLIC_API_URL=http://localhost:2024与NEXT_PUBLIC_ASSISTANT_ID=agent,重启后应用会直接进聊天页,不再显示配置表单。
三、界面里藏了什么:前端源码结构速览
想定制界面?前端结构非常清晰,几个关键入口:
- 连接与流式核心:src/providers/Stream.tsx——封装了
useStream,负责连接服务器、提交运行(run)、处理流事件 - 会话容器:src/components/thread/index.tsx——消息列表、自动吸底滚动、新建会话按钮都在这里
- 消息渲染:src/components/thread/messages/ 下的
ai.tsx、human.tsx、tool-calls.tsx分别负责 AI 回复、用户消息与工具调用卡片 - 工具调用表:src/components/thread/agent-inbox/components/tool-call-table.tsx
- 主题与样式:src/app/globals.css + Tailwind CSS
技术栈一览:Next.js 16、React 19、TypeScript、Tailwind CSS、shadcn/ui 风格组件(src/components/ui/),依赖清单见 package.json。
四、进阶玩法:控制消息显示与 Artifact 侧栏
4.1 隐藏不想让用户看到的消息
有时智能体内部会产出"过程性"消息,不想刷屏?两种优雅方式:
- 阻止流式显示:给聊天模型配置加上
langsmith:nostream标签,UI 就不会实时渲染它的输出; - 彻底隐藏:把消息的
id加上do-not-render-前缀再存入状态,UI 会直接过滤掉这类消息,流式与落库后都不显示。
4.2 在聊天右侧弹出 Artifact 面板
Agent Chat UI 支持在聊天右侧渲染独立内容面板(Artifact),适合展示长文、报告等"重内容"。核心思路:通过 thread.meta.artifact 拿到侧栏上下文,再用内置的 Artifact 组件渲染。参考实现:src/components/thread/artifact.tsx。
五、走向生产:API 代理让密钥不落地
默认配置是"客户端直连",适合本地开发;生产环境绝不能把 LangSmith API Key 塞给每个用户。好消息是:仓库已内置 API 代理方案(langgraph-nextjs-api-passthrough),入口在 src/app/api/[..._path]/route.ts——它会把所有 /api/* 请求代理到你的 LangGraph 部署,并在服务端注入密钥。
只需设置 4 个环境变量:
NEXT_PUBLIC_ASSISTANT_ID="agent" # 助手 ID(客户端可见)
LANGGRAPH_API_URL="https://your-langgraph-deployment" # LangGraph 部署地址
NEXT_PUBLIC_API_URL="https://your-website.com/api" # 你的站点 + /api
LANGSMITH_API_KEY="lsv2_..." # 仅服务端使用,切勿加 NEXT_PUBLIC_ 前缀
进阶方案是为 LangGraph 部署配置自定义鉴权(Custom Auth),客户端无需 API Key,通过请求头携带 Bearer Token 即可,具体做法可参考 Stream.tsx 中 useTypedStream 的 defaultHeaders 用法。
写在最后
lca-lc-foundations 的这份"附赠品",本质是演示了一条完整的智能体产品化路径:后端用 LangGraph 编排智能体(如 3.5_email_agent.py 的邮件助手),前端用 Next.js 聊天界面承载交互。从本地 langgraph dev 到生产 API 代理,每一步仓库里都给你留了现成的代码。
如果你正在学习 LangChain / LangGraph,强烈建议按 Module 1 → 2 → 3 的顺序过一遍 notebooks/ 目录,再用本文的 3 步流程,亲手给你的第一个智能体套上这个华丽的聊天前端 👨💻
