langchain-ai/agent-chat-ui

🦜💬 Web app for interacting with any LangGraph agent (PY & TS) via a chat interface.

Agent Chat UI – 是什么

Agent Chat UI 是一个小型 Next.js Web 应用，可与任何 LangGraph 服务器（运行 LangChain 风格代理图的后端）进行对话。您将 UI 指向一个 LangGraph 端点，提供想要使用的助手/图的 ID，然后打开一个聊天窗口，每个用户输入都会发送到服务器，LLM 生成的回复会以流式方式返回。

该项目本质上是 LangGraph 代理的前端客户端，附带一些便利功能：

一个快速启动表单（或环境变量覆盖）来配置服务器 URL、助手 ID 和可选的 LangSmith API 密钥。
支持通过特殊标签（langsmith:nostream、langsmith:do-not-render）隐藏流式消息或永久抑制消息。
一个工件（artifacts）侧边栏——图可返回的额外数据（例如生成的文件、可视化内容）——通过自定义 React 钩子暴露。
生产部署指南，包括注入 LangSmith 密钥的 API 透传代理，以及可选的自定义身份验证以增强安全性。

快速开始（本地开发）

# 创建新项目（或克隆仓库）
npx create-agent-chat-app
# 或者
git clone https://github.com/langchain-ai/agent-chat-ui.git && cd agent-chat-ui

# 安装依赖（推荐使用 pnpm）
pnpm install

# 启动开发服务器
pnpm dev   # → http://localhost:3000

当应用加载后，您会看到一个简短的表单。填写以下内容：

部署 URL – 您的 LangGraph 服务器的 HTTP 地址。
助手/图 ID – 您想对话的代理的名称或 UUID。
LangSmith API 密钥 – 仅当服务器需要 LangSmith 密钥时才需要（例如使用内置的 Agent Builder 部署时）。
使用 Agent Builder 构建 – 如果服务器是通过 LangSmith 的 Agent Builder 创建的，请启用此选项；它会自动选择正确的认证方案。

点击继续后，您将进入聊天视图。

跳过设置表单运行

您可以通过设置三个环境变量（或添加到基于 .env.example 的 .env 文件中）跳过交互式表单：

NEXT_PUBLIC_API_URL=http://localhost:2024   # LangGraph 端点
NEXT_PUBLIC_ASSISTANT_ID=agent            # 图/助手 ID
NEXT_PUBLIC_AUTH_SCHEME=                  # 例如，Agent Builder 用 "langsmith-api-key"

当这些变量存在时，UI 会立即连接。

控制 UI 显示内容

隐藏流式输出

在聊天模型配置中添加标签 langsmith:nostream。UI 会监听 on_chat_model_stream 事件；该标签会抑制这些事件，因此用户只看到最终消息。

# Python 示例
model = ChatAnthropic().with_config({"tags": ["langsmith:nostream"]})

// TypeScript 示例
const model = new ChatAnthropic().withConfig({ tags: ["langsmith:nostream"] })

完全隐藏某条消息

在消息 id 前缀加上 do-not-render- 并添加标签 langsmith:do-not-render。UI 会过滤掉任何以该前缀开头的消息 ID，因此内容永远不会出现在聊天窗格中。

result = model.invoke([messages])
result.id = f"do-not-render-{result.id}"
return {"messages": [result]}

const result = await model.invoke([messages])
result.id = `do-not-render-${result.id}`
return { messages: [result] }

渲染工件

LangGraph 图可以返回额外数据到 thread.meta.artifact。UI 提供了一个钩子 useArtifact，可提供：

一个 React 组件（Artifact），用于在可折叠侧边栏中渲染内容。
状态（open, setOpen）以控制面板可见性。
包含您存储的任何内容的原始 context 对象。

一个最小使用模式如下：

import { useArtifact } from "../utils/use-artifact"

export function Writer({title, content, description}) {
  const [Artifact, {open, setOpen}] = useArtifact()
  return (
    <>
      <div => setOpen(!open)} className="cursor-pointer rounded-lg border p-4">
        <p className="font-medium">{title}</p>
        <p className="text-sm text-gray-500">{description}</p>
      </div>
      <Artifact title={title}>
        <p className="whitespace-pre-wrap p-4">{content}</p>
      </Artifact>
    </>
  )
}

这使开发者能够展示生成的文件、图表或任何自定义 UI 与聊天并列。

生产部署

直接将 UI 连接到公开的 LangGraph 端点会暴露每个用户的 LangSmith 密钥。该仓库提供了两种推荐方式来避免此问题：

1. API 透传（最快）

安装 langgraph-nextjs-api-passthrough 包（已捆绑）。
部署 Next.js 应用（例如 Vercel）。内置的 /api 路由将请求代理到您的 LangGraph 服务器，并在 服务器端 注入 LangSmith 密钥。

在部署平台设置以下环境变量：

NEXT_PUBLIC_ASSISTANT_ID=agent
LANGGRAPH_API_URL=https://my-agent.default.us.langgraph.app   # 您的 LangGraph 部署
NEXT_PUBLIC_API_URL=https://my-website.com/api                # 此 UI + /api 的 URL
LANGSMITH_API_KEY=lsv2_…                                      # 秘密，不以 NEXT_PUBLIC_ 开头

重要：透传不认证调用者。请添加自己的网关（例如 Vercel 边缘中间件）或使用下面的高级自定义认证选项。

2. 自定义认证（更安全）

按照 LangGraph 的自定义认证文档（Python 或 TypeScript）设置 LangGraph 服务器，要求 Bearer 令牌或其他方案。

在 UI 中，修改 useTypedStream（或底层的 useStream）以在请求头中附加令牌：

const streamValue = useTypedStream({
  apiUrl: process.env.NEXT_PUBLIC_API_URL,
  assistantId: process.env.NEXT_PUBLIC_ASSISTANT_ID,
  defaultHeaders: { Authentication: `Bearer ${myToken}` },
  // …其他选项
})

这使客户端可以直接与 LangGraph 服务器通信，而无需暴露 LangSmith 密钥。

谁会使用它？

需要现成聊天 UI 用于演示或内部测试的 LangGraph 代理开发者。
需要轻量级前端将 LLM 驱动的助手提供给最终用户，而无需从零构建自定义 UI 的 产品团队。
希望在保持前端代码最小化的同时实验流式控制或工件渲染的 研究人员。

TL;DR

克隆或 npx create-agent-chat-app → pnpm dev。
将 UI 指向 LangGraph 服务器（URL + 助手 ID）。可选地提供 LangSmith 密钥。
使用标签（langsmith:nostream、langsmith:do-not-render）隐藏消息。
通过 useArtifact 钩子渲染额外数据。
生产环境中，要么通过内置 API 透传（使用秘密 LangSmith 密钥）或在 LangGraph 侧设置自定义认证。