6.3 Agent Chat UI
Agent Chat UI 是一个基于 Next.js 的 Web 应用，为 LangGraph 代理提供对话式交互界面。
概述
Agent Chat UI 是 LangChain 官方提供的开源聊天界面，支持与任何具有 messages 键的 LangGraph 服务器进行交互。它提供实时聊天、工具可视化和高级调试功能。
核心特性
| 特性 | 说明 |
|---|---|
| 多语言支持 | 支持 Python 和 TypeScript 编写的 LangGraph 代理 |
| 工具可视化 | 自动渲染工具调用和结果 |
| 消息控制 | 可隐藏流式消息或永久隐藏特定消息 |
| Artifact 渲染 | 侧边面板展示生成的内容 |
| 生产就绪认证 | 多种认证方式，包括 API 透传和自定义认证 |
| 环境变量配置 | 支持预配置跳过设置表单 |
架构概览
┌─────────────────────────────────────────────────────────────┐
│ Agent Chat UI │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Browser │◀──▶│ Next.js │◀──▶│ LangGraph │ │
│ │ (用户) │ │ Frontend │ │ Server │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ LangSmith │ │
│ │ (可选) │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘快速开始
方式一：托管版本
访问在线部署版本：agentchat.vercel.app
- 打开网站
- 输入代理部署 URL
- 填写 Graph ID
- 开始对话
方式二：使用 NPM 创建
bash
# 创建新项目
npx create-agent-chat-app --project-name my-chat-ui
# 进入目录
cd my-chat-ui
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev应用将在 http://localhost:3000 运行。
方式三：克隆仓库
bash
# 克隆仓库
git clone https://github.com/langchain-ai/agent-chat-ui.git
# 进入目录
cd agent-chat-ui
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev初始配置
首次启动时，需要配置以下信息：
┌─────────────────────────────────────────────────────────────┐
│ Agent Chat UI 配置 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Deployment URL: │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ http://localhost:2024 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Assistant/Graph ID: │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ agent │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ LangSmith API Key (可选，生产环境需要): │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ lsv2_... │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ [Connect] │
│ │
└─────────────────────────────────────────────────────────────┘配置说明
| 字段 | 说明 | 示例 |
|---|---|---|
| Deployment URL | LangGraph 服务器地址 | http://localhost:2024 |
| Graph ID | langgraph.json 中定义的图名称 | agent |
| LangSmith API Key | 仅生产部署需要 | lsv2_xxx... |
环境变量配置
使用环境变量跳过配置表单：
bash
# .env.local
NEXT_PUBLIC_API_URL=http://localhost:2024
NEXT_PUBLIC_ASSISTANT_ID=agent
LANGSMITH_API_KEY=lsv2_your_api_key界面功能
聊天界面
┌─────────────────────────────────────────────────────────────┐
│ Agent Chat [Settings] │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ User: 帮我搜索今天的天气 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Assistant: 正在搜索天气信息... │ │
│ │ │ │
│ │ [Tool Call: weather_search] │ │
│ │ ├── city: "北京" │ │
│ │ └── date: "today" │ │
│ │ │ │
│ │ [Tool Result] │ │
│ │ └── "晴，25°C，湿度 45%" │ │
│ │ │ │
│ │ 今天北京天气晴朗，温度 25°C，湿度 45%。 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 输入消息... [Send] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘工具调用可视化
Agent Chat UI 自动渲染工具调用过程：
┌──────────────────────────────────────┐
│ Tool: weather_search │
├──────────────────────────────────────┤
│ Arguments: │
│ city: "北京" │
│ date: "2024-01-15" │
├──────────────────────────────────────┤
│ Result: │
│ 天气：晴 │
│ 温度：25°C │
│ 湿度：45% │
└──────────────────────────────────────┘Artifact 侧边栏
生成的内容可在侧边面板中展示：
┌─────────────────────────────┬───────────────────────────┐
│ 聊天主界面 │ Artifact 面板 │
│ │ │
│ User: 生成一个柱状图 │ ┌───────────────────┐ │
│ │ │ │ │
│ Assistant: 好的，我来 │ │ [Chart] │ │
│ 生成一个柱状图... │ │ █ █ │ │
│ │ │ █ █ █ │ │
│ [查看 Artifact ▶] │ │ █ █ █ █ │ │
│ │ │ │ │
│ │ └───────────────────┘ │
│ │ │
│ │ [Download] [Copy] │
└─────────────────────────────┴───────────────────────────┘消息控制
隐藏消息
在代理代码中标记要隐藏的消息：
python
from langchain_core.messages import AIMessage
# 创建隐藏消息
hidden_message = AIMessage(
content="正在处理中...",
additional_kwargs={
"hide_in_ui": True # UI 中不显示
}
)隐藏流式消息
对于中间处理步骤，可以隐藏流式输出：
python
# 在代理配置中
agent_config = {
"hide_streaming_messages": True,
"show_only_final": True,
}生产部署
方式一：API 透传（推荐）
使用中间件包处理服务端认证：
bash
# 安装中间件包
npm install langgraph-nextjs-api-passthroughtypescript
// pages/api/langgraph/[...path].ts
import { createHandler } from 'langgraph-nextjs-api-passthrough';
export default createHandler({
langGraphUrl: process.env.LANGGRAPH_URL,
langSmithApiKey: process.env.LANGSMITH_API_KEY,
});优点：
- API Key 不暴露在前端
- 服务端处理认证
- 安全性更高
方式二：自定义认证
使用 LangGraph 的认证框架：
python
# Python 示例
from langgraph.auth import Auth
auth = Auth(
verify_token=my_token_verifier,
get_user=my_user_getter,
)
# 创建带认证的服务器
server = create_server(
graph=my_graph,
auth=auth,
)typescript
// TypeScript 示例
import { Auth } from '@langchain/langgraph';
const auth = new Auth({
verifyToken: myTokenVerifier,
getUser: myUserGetter,
});连接本地代理
配合 LangGraph Dev 使用
- 启动 LangGraph 开发服务器：
bash
langgraph dev服务器运行在
http://localhost:2024启动 Agent Chat UI：
bash
cd agent-chat-ui
pnpm dev- 在 UI 中输入：
- Deployment URL:
http://localhost:2024 - Graph ID:
agent（或您定义的名称）
- Deployment URL:
连接示意图
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Browser │────▶│ Chat UI │────▶│ LangGraph │
│ :3000 │ │ Next.js │ │ Dev Server │
└──────────────┘ └──────────────┘ │ :2024 │
└──────────────┘自定义开发
项目结构
agent-chat-ui/
├── src/
│ ├── components/
│ │ ├── ChatMessage.tsx
│ │ ├── ToolCall.tsx
│ │ └── ArtifactPanel.tsx
│ ├── hooks/
│ │ └── useChat.ts
│ ├── pages/
│ │ ├── index.tsx
│ │ └── api/
│ └── styles/
├── public/
├── package.json
└── next.config.js自定义消息组件
tsx
// src/components/CustomMessage.tsx
import React from 'react';
interface MessageProps {
role: 'user' | 'assistant' | 'tool';
content: string;
toolCalls?: ToolCall[];
}
export function CustomMessage({ role, content, toolCalls }: MessageProps) {
return (
<div className={`message message-${role}`}>
<div className="message-avatar">
{role === 'user' ? '👤' : '🤖'}
</div>
<div className="message-content">
{content}
{toolCalls && (
<div className="tool-calls">
{toolCalls.map((call, i) => (
<ToolCallComponent key={i} call={call} />
))}
</div>
)}
</div>
</div>
);
}自定义样式
css
/* src/styles/custom.css */
.message {
display: flex;
gap: 12px;
padding: 16px;
border-radius: 8px;
}
.message-user {
background: #f0f0f0;
}
.message-assistant {
background: #e8f4f8;
}
.tool-calls {
margin-top: 8px;
padding: 8px;
background: #f5f5f5;
border-radius: 4px;
font-family: monospace;
}故障排除
常见问题
Q: 无法连接到本地服务器？
A: 检查以下几点：
- 确保
langgraph dev正在运行 - 检查端口 2024 未被占用
- 检查 CORS 设置
Q: 工具调用不显示？
A: 确保代理返回的消息包含 tool_calls 字段：
python
# 正确的工具调用响应
response = AIMessage(
content="",
tool_calls=[
{"name": "tool_name", "args": {...}, "id": "call_xxx"}
]
)Q: 认证失败？
A: 检查 API Key 配置：
- 本地开发：可以不配置
- 生产环境：必须配置
LANGSMITH_API_KEY
最佳实践
| 场景 | 建议 |
|---|---|
| 本地开发 | 使用 npx create-agent-chat-app 快速启动 |
| 团队协作 | 克隆仓库，自定义组件 |
| 生产部署 | 使用 API 透传保护密钥 |
| 复杂 UI | 扩展组件系统 |
| 品牌定制 | 修改样式文件 |
相关资源
- GitHub 仓库：langchain-ai/agent-chat-ui
- 视频教程：YouTube 安装指南
- 在线体验：agentchat.vercel.app
- NPM 包：create-agent-chat-app
上一节：6.2 Test