给智能体套上华丽前端:lca-lc-foundations 附赠 Next.js Agent Chat UI 实战

原创2026-11-02 15:34:142,332 阅读

给智能体套上华丽前端: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 键,它就能通过聊天界面与之对话。

LangChain Agent Chat UI 聊天界面项目的官方标志

它的"娘家"位置就在课程仓库里:

开箱即得的功能包括:

能力 说明
⚡ 流式渲染 基于 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,重启后应用会直接进聊天页,不再显示配置表单。

三、界面里藏了什么:前端源码结构速览

想定制界面?前端结构非常清晰,几个关键入口:

技术栈一览:Next.js 16、React 19、TypeScript、Tailwind CSS、shadcn/ui 风格组件(src/components/ui/),依赖清单见 package.json。

四、进阶玩法:控制消息显示与 Artifact 侧栏

4.1 隐藏不想让用户看到的消息

有时智能体内部会产出"过程性"消息,不想刷屏?两种优雅方式:

  1. 阻止流式显示:给聊天模型配置加上 langsmith:nostream 标签,UI 就不会实时渲染它的输出;
  2. 彻底隐藏:把消息的 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 步流程,亲手给你的第一个智能体套上这个华丽的聊天前端 👨‍💻

登录后查看全文
lca-lc-foundations