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 邊緣設定自訂驗證。