代理聊天 UI

代理聊天 UI 是一个 Next.js 应用程序，它通过聊天界面使用户能够与任何具有 messages 键的 LangGraph 服务器进行对话。

[!NOTE] 🎥 观看视频设置指南 这里。

设置

[!TIP] 不想在本地运行应用？请使用部署好的站点：agentchat.vercel.app！

首先，克隆仓库，或者运行 npx 命令：

npx create-agent-chat-app

或者

git clone https://github.com/langchain-ai/agent-chat-ui.git

cd agent-chat-ui

安装依赖：

pnpm install

运行应用：

pnpm dev

应用将可在 http://localhost:3000 访问。

使用

一旦应用运行起来（或使用部署好的站点），系统会提示您输入以下内容：

• 部署 URL：您想要聊天的 LangGraph 服务器的 URL。这可以是生产环境或开发环境的 URL。
• 助手/图 ID：用于在通过聊天界面获取和提交运行时使用的图名称或助手 ID。
• LangSmith API 密钥：（仅连接到已部署的 LangGraph 服务器时需要）用于对发送到 LangGraph 服务器的请求进行身份验证的 LangSmith API 密钥。
• 由 Agent Builder 构建：对于 Agent Builder 部署，请开启此选项。这会自动将认证方案设置为 langsmith-api-key。

输入这些值后，点击 继续。随后您将被重定向到聊天界面，可以在那里开始与您的 LangGraph 服务器对话。

环境变量

您可以通过设置以下环境变量来跳过初始设置表单：

NEXT_PUBLIC_API_URL=http://localhost:2024
NEXT_PUBLIC_ASSISTANT_ID=agent
NEXT_PUBLIC_AUTH_SCHEME=

[!NOTE] 如果您要连接到 LangSmith Agent Builder 部署，请设置 NEXT_PUBLIC_AUTH_SCHEME=langsmith-api-key。

[!TIP] 如果您想连接到生产环境的 LangGraph 服务器，请阅读 进入生产环境 部分。

要使用这些变量：

1. 将 .env.example 文件复制到名为 .env 的新文件中。
2. 在 .env 文件中填写相应的值。
3. 重启应用程序。

当设置了这些环境变量时，应用程序将直接使用它们，而不会显示设置表单。

在聊天中隐藏消息

您可以通过两种主要方式控制代理聊天 UI 中消息的可见性：

1. 阻止实时流式传输：

要阻止消息在 LLM 调用过程中“实时”显示，可以在聊天模型的配置中添加 langsmith:nostream 标签。UI 通常使用 on_chat_model_stream 事件来渲染流式消息；该标签会阻止带有此标签的模型发出这些事件。

Python 示例：

from langchain_anthropic import ChatAnthropic

# 通过 .with_config 方法添加标签
model = ChatAnthropic().with_config(
    config={"tags": ["langsmith:nostream"]}
)

TypeScript 示例：

import { ChatAnthropic } from "@langchain/anthropic";

const model = new ChatAnthropic()
  // 通过 .withConfig 方法添加标签
  .withConfig({ tags: ["langsmith:nostream"] });

注意： 即使以这种方式隐藏了流式传输，如果消息在不作进一步修改的情况下保存到图的状态中，它仍然会在 LLM 调用完成后显示。

2. 永久隐藏消息：

要确保消息在聊天 UI 中 始终 不显示（无论是在流式传输期间还是保存到状态之后），请在将其添加到图的状态之前，先为其 id 字段加上前缀 do-not-render-，同时在聊天模型的配置中添加 langsmith:do-not-render 标签。UI 会明确过滤掉所有 id 以该前缀开头的消息。

Python 示例：

result = model.invoke([messages])
# 在保存到状态之前给 ID 加上前缀
result.id = f"do-not-render-{result.id}"
return {"messages": [result]}

TypeScript 示例：

const result = await model.invoke([messages]);
// 在保存到状态之前给 ID 加上前缀
result.id = `do-not-render-${result.id}`;
return { messages: [result] };

这种方法可确保消息完全不会显示在用户界面上。

渲染工件

代理聊天 UI 支持在聊天中渲染工件。工件会显示在聊天右侧的侧边栏中。要渲染工件，您可以从 thread.meta.artifact 字段中获取工件上下文。以下是一个用于获取工件上下文的示例实用钩子：

export function useArtifact<TContext = Record<string, unknown>>() {
  type Component = (props: {
    children: React.ReactNode;
    title?: React.ReactNode;
  }) => React.ReactNode;

  type Context = TContext | undefined;

  type Bag = {
    open: boolean;
    setOpen: (value: boolean | ((prev: boolean) => boolean)) => void;

    context: Context;
    setContext: (value: Context | ((prev: Context) => Context)) => void;
  };

  const thread = useStreamContext<
    { messages: Message[]; ui: UIMessage[] },
    { MetaType: { artifact: [Component, Bag] } }
  >();

  return thread.meta?.artifact;
}

之后，您可以使用 useArtifact 钩子中的 Artifact 组件来渲染其他内容：

import { useArtifact } from "../utils/use-artifact";
import { LoaderIcon } from "lucide-react";

export function Writer(props: {
  title?: string;
  content?: string;
  description?: string;
}) {
  const [Artifact, { open, setOpen }] = useArtifact();

  return (
    <>
      <div
        onClick={() => setOpen(!open)}
        className="cursor-pointer rounded-lg border p-4"
      >
        <p className="font-medium">{props.title}</p>
        <p className="text-sm text-gray-500">{props.description}</p>
      </div>

      <Artifact title={props.title}>
        <p className="p-4 whitespace-pre-wrap">{props.content}</p>
      </Artifact>
    </>
  );
}

进入生产环境

一旦您准备好进入生产环境，就需要更新连接方式以及对部署的请求进行身份验证。默认情况下，代理聊天 UI 是为本地开发设计的，它会直接从客户端连接到您的 LangGraph 服务器。但如果您想进入生产环境，这种方式就不再可行，因为这要求每个用户都拥有自己的 LangSmith API 密钥，并自行设置 LangGraph 配置。

生产环境设置

要将代理聊天 UI 投入生产，您需要选择以下两种方式之一来对发送到 LangGraph 服务器的请求进行身份验证。下面我将介绍这两种方案：

快速入门 - API 透传

将 Agent Chat UI 投入生产环境的最快方式是使用 API 透传 包（NPM 链接在此）。该包提供了一种简单的方法，用于将请求代理到您的 LangGraph 服务器，并为您处理身份验证。

此仓库已包含您开始使用此方法所需的所有代码。您唯一需要做的配置就是设置正确的环境变量。

NEXT_PUBLIC_ASSISTANT_ID="agent"
# 这应该是您的 LangGraph 服务器的部署 URL
LANGGRAPH_API_URL="https://my-agent.default.us.langgraph.app"
# 这应该是您网站的 URL 加上 "/api"。这是您连接到 API 代理的方式
NEXT_PUBLIC_API_URL="https://my-website.com/api"
# 您的 LangSmith API 密钥，它会被注入到 API 代理内部的请求中
LANGSMITH_API_KEY="lsv2_..."

下面我们来逐一说明这些环境变量的作用：

• NEXT_PUBLIC_ASSISTANT_ID：当通过聊天界面获取和提交运行时，您希望使用的助手的 ID。由于这不是敏感信息，因此仍需加上 NEXT_PUBLIC_ 前缀，并且我们在客户端提交请求时会用到它。
• LANGGRAPH_API_URL：您的 LangGraph 服务器的 URL。这应该是生产环境的部署 URL。
• NEXT_PUBLIC_API_URL：您网站的 URL 加上 /api。这是您连接到 API 代理的方式。对于 Agent Chat 演示，此处应设置为 https://agentchat.vercel.app/api。您应该将其设置为您生产环境的实际 URL。
• LANGSMITH_API_KEY：用于对发送到 LangGraph 服务器的请求进行身份验证的 LangSmith API 密钥。同样，不要为其添加 NEXT_PUBLIC_ 前缀，因为它属于敏感信息，仅在服务器端由 API 代理将其注入到发送至您部署的 LangGraph 服务器的请求中时才会使用。

如需深入了解，请参阅 LangGraph Next.js API 透传 的文档。

高级设置 - 自定义身份验证

在您的 LangGraph 部署中使用自定义身份验证是一种更高级、更健壮的方式来验证对 LangGraph 服务器的请求。通过自定义身份验证，您可以允许来自客户端的请求无需 LangSmith API 密钥即可发起。此外，您还可以为请求指定自定义的访问控制规则。

要在您的 LangGraph 部署中设置此功能，请阅读 LangGraph 自定义身份验证的相关文档，分别适用于 Python 和 TypeScript。

完成部署上的设置后，您需要对 Agent Chat UI 进行以下更改：

1. 配置任何额外的 API 请求，以从您的 LangGraph 部署获取身份验证令牌，该令牌将用于对来自客户端的请求进行身份验证。
2. 将 NEXT_PUBLIC_API_URL 环境变量设置为您的生产环境 LangGraph 部署 URL。
3. 将 NEXT_PUBLIC_ASSISTANT_ID 环境变量设置为您希望在通过聊天界面获取和提交运行时使用的助手的 ID。
4. 修改 useTypedStream（useStream 的扩展）钩子，以便通过请求头将您的身份验证令牌传递给 LangGraph 服务器：

const streamValue = useTypedStream({
  apiUrl: process.env.NEXT_PUBLIC_API_URL,
  assistantId: process.env.NEXT_PUBLIC_ASSISTANT_ID,
  // ... 其他字段
  defaultHeaders: {
    Authentication: `Bearer ${addYourTokenHere}`, // 在这里您需要传递您的身份验证令牌
  },
});

Agent Chat UI 快速上手指南

Agent Chat UI 是一个基于 Next.js 构建的应用程序，允许用户通过聊天界面与任何带有 messages 键的 LangGraph 服务器进行交互。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 建议安装 LTS 版本（推荐 v18+）。
• 包管理器: 本项目推荐使用 pnpm。
  • 国内开发者可配置国内镜像源加速安装：

  npm config set registry https://registry.npmmirror.com
  

  • 安装 pnpm (如果尚未安装):

  npm install -g pnpm
  

• LangGraph 服务器: 您需要有一个正在运行的 LangGraph 服务器（本地开发或云端部署），并知晓其 URL 和 Assistant/Graph ID。

安装步骤

您可以选择使用 npx 一键创建项目，或通过 git 克隆源码。

方式一：使用 npx 快速创建（推荐）

npx create-agent-chat-app

方式二：手动克隆仓库

git clone https://github.com/langchain-ai/agent-chat-ui.git

cd agent-chat-ui

安装依赖并启动

进入项目目录后，执行以下命令安装依赖并启动开发服务器：

pnpm install

pnpm dev

启动成功后，应用将在 http://localhost:3000 运行。

提示: 如果您不想在本地运行，可以直接访问官方部署站点：agentchat.vercel.app。

基本使用

应用启动后（或使用在线版本时），您将看到一个初始化配置表单。请填写以下信息以连接您的 LangGraph 服务：

1. Deployment URL: 您要连接的 LangGraph 服务器地址（可以是本地 http://localhost:2024 或生产环境 URL）。
2. Assistant/Graph ID: 用于获取和提交运行的图名称或助手 ID。
3. LangSmith API Key: （仅连接已部署的 LangGraph 服务器时需要）用于请求认证的 LangSmith API 密钥。
4. Built with Agent Builder: 如果是 Agent Builder 部署，请开启此选项，它将自动设置认证方案为 langsmith-api-key。

填写完毕后点击 Continue，即可进入聊天界面开始与您的 AI 助手交互。

进阶：通过环境变量跳过配置表单

如果您希望直接启动应用而不显示配置表单，可以在项目根目录创建 .env 文件（复制 .env.example），并填入以下变量：

NEXT_PUBLIC_API_URL=http://localhost:2024
NEXT_PUBLIC_ASSISTANT_ID=agent
NEXT_PUBLIC_AUTH_SCHEME=

• 注意: 若连接 LangSmith Agent Builder 部署，需设置 NEXT_PUBLIC_AUTH_SCHEME=langsmith-api-key。
• 修改 .env 文件后，请重启应用 (pnpm dev) 生效。