catonline_ai/vw-agentic-rag/docs/topics/assistant-ui.md

给你一份可直接落地的前端实现：我已把完整的 React/Next.js 单文件示例（含自定义 Tool UI、样式与 Data Stream 运行时接入）放到右侧画布里。按下面步骤即可跑起来：

```
"use client";

// ------------------------------------------------------------
// assistant-ui × LangGraph(FastAPI) 流式前端 (Data Stream 协议)
// ------------------------------------------------------------
// 说明：
// 1) 该文件可作为 Next.js `app/page.tsx` 或任意 React 页面组件使用。
// 2) 依赖：
//    npm i @assistant-ui/react @assistant-ui/react-ui @assistant-ui/react-data-stream \
//          @assistant-ui/react-markdown remark-gfm @radix-ui/react-tooltip \
//          @radix-ui/react-slot lucide-react class-variance-authority clsx tailwindcss-animate
// 3) 样式：
//    - 在 tailwind.config.ts 中加入插件：
//        plugins: [
//          require("tailwindcss-animate"),
//          require("@assistant-ui/react-ui/tailwindcss")({ components: ["thread", "thread-list"], shadcn: true })
//        ]
//    - 在全局布局文件(如 app/layout.tsx)中引入：
//        import "@assistant-ui/react-ui/styles/index.css";
// 4) 运行约定：后端 FastAPI 暴露 POST /api/chat，返回基于 Data Stream 协议的 SSE。
//    - 响应头需包含：'x-vercel-ai-ui-message-stream': 'v1'
//    - 事件类型至少包含：start、text-start / text-delta / text-end、
//      tool-input-start / tool-input-delta / tool-input-available、
//      tool-output-available、start-step、finish-step、finish、[DONE]
//    - 这些事件来自 LangGraph 的 run/工具事件映射（由后端转成 Data Stream 协议）。
// ------------------------------------------------------------

import React, { useMemo } from "react";
import {
  AssistantRuntimeProvider,
  makeAssistantToolUI,
} from "@assistant-ui/react";
import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
import { Thread } from "@assistant-ui/react-ui";
import { Check, Globe, Search, Terminal } from "lucide-react";

// ---------------------------
// 1) 自定义 Tool UI（可选）
// ---------------------------
// 将 LangGraph 工具事件以特定工具名注册到前端 UI 中，
// toolName 需与后端发送的工具名完全一致。

// Web 搜索工具 UI（示例：toolName: "web_search"）
const WebSearchToolUI = makeAssistantToolUI<{ query: string }, { results: Array<{ title: string; url: string; snippet?: string }>; took_ms?: number }>({
  toolName: "web_search",
  render: ({ args, result, status }) => {
    return (
      <div className="rounded-2xl border bg-card text-card-foreground p-3 my-2">
        <div className="flex items-center gap-2 text-sm font-medium opacity-80">
          <Search className="h-4 w-4" />
          <span>Web 搜索</span>
          <span className="opacity-60">— {args?.query ?? ""}</span>
        </div>
        {status.type === "running" && (
          <p className="text-sm mt-2 opacity-80">正在搜索…</p>
        )}
        {status.type === "requires_action" && (
          <p className="text-sm mt-2 opacity-80">等待后端确认…</p>
        )}
        {status.type === "incomplete" && (
          <p className="text-sm mt-2 text-destructive">搜索失败</p>
        )}
        {status.type === "complete" && result && (
          <ul className="mt-2 space-y-2">
            {result.results?.slice(0, 6).map((r, i) => (
              <li key={i} className="text-sm">
                <a className="underline underline-offset-4" href={r.url} target="_blank" rel="noreferrer">
                  {r.title}
                </a>
                {r.snippet && <p className="opacity-80 mt-1">{r.snippet}</p>}
              </li>
            ))}
            {typeof result.took_ms === "number" && (
              <li className="text-xs opacity-60">耗时 {result.took_ms}ms</li>
            )}
          </ul>
        )}
      </div>
    );
  },
});

// URL 抓取工具 UI（示例：toolName: "fetch_url"）
const FetchUrlToolUI = makeAssistantToolUI<{ url: string }, { title?: string; content?: string } | { error: string }>({
  toolName: "fetch_url",
  render: ({ args, result, status }) => {
    return (
      <div className="rounded-2xl border bg-card text-card-foreground p-3 my-2">
        <div className="flex items-center gap-2 text-sm font-medium opacity-80">
          <Globe className="h-4 w-4" />
          <span>抓取网页</span>
          <span className="opacity-60">— {args?.url ?? ""}</span>
        </div>
        {status.type === "running" && (
          <p className="text-sm mt-2 opacity-80">抓取中…</p>
        )}
        {status.type === "complete" && result && "error" in result && (
          <p className="text-sm mt-2 text-destructive">错误：{result.error}</p>
        )}
        {status.type === "complete" && result && !("error" in result) && (
          <div className="mt-2 text-sm space-y-1">
            {result.title && <p className="font-medium">{result.title}</p>}
            {result.content && (
              <p className="opacity-80 line-clamp-4" title={result.content}>
                {result.content}
              </p>
            )}
          </div>
        )}
      </div>
    );
  },
});

// Python 代码执行 UI（示例：toolName: "python" 或 "run_python"）
const PythonToolUI = makeAssistantToolUI<{ code: string }, { stdout?: string; stderr?: string; elapsed_ms?: number }>({
  toolName: "python",
  render: ({ args, result, status }) => {
    return (
      <div className="rounded-2xl border bg-card text-card-foreground p-3 my-2">
        <div className="flex items-center gap-2 text-sm font-medium opacity-80">
          <Terminal className="h-4 w-4" />
          <span>执行 Python</span>
        </div>
        <pre className="bg-muted/60 rounded-xl p-3 mt-2 text-xs overflow-auto max-h-64">
{args?.code}
        </pre>
        {status.type === "running" && (
          <p className="text-sm mt-2 opacity-80">运行中…</p>
        )}
        {status.type === "complete" && result && (
          <div className="mt-2 text-sm space-y-2">
            {result.stdout && (
              <div>
                <p className="font-medium">stdout</p>
                <pre className="bg-muted/60 rounded-xl p-3 mt-1 text-xs overflow-auto max-h-64">{result.stdout}</pre>
              </div>
            )}
            {result.stderr && (
              <div>
                <p className="font-medium">stderr</p>
                <pre className="bg-muted/60 rounded-xl p-3 mt-1 text-xs overflow-auto max-h-64 text-red-600">{result.stderr}</pre>
              </div>
            )}
            {typeof result.elapsed_ms === "number" && (
              <div className="flex items-center gap-2 text-xs opacity-60">
                <Check className="h-3 w-3" /> 用时 {result.elapsed_ms}ms
              </div>
            )}
          </div>
        )}
      </div>
    );
  },
});

// ---------------------------
// 2) Runtime Provider（Data Stream 协议，SSE）
// ---------------------------
// useDataStreamRuntime 会：
// - 在发送消息后，自动通过 EventSource 连接到 /api/chat 的 SSE 流；
// - 解析 Data Stream 协议事件并更新到线程消息；
// - 支持多步/工具调用的可视化（配合上方 Tool UIs）。

function AssistantProvider({ children }: { children: React.ReactNode }) {
  const runtime = useDataStreamRuntime({
    api: "/api/chat", // 对应 FastAPI 的 POST /api/chat
    // 如果需要自定义 headers/cookies，可传入 fetcher:
    // fetcher: (input, init) => fetch(input, { ...init, credentials: "include" })
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>{children}</AssistantRuntimeProvider>
  );
}

// ---------------------------
// 3) 主界面：Thread（预设主题，开箱即用）
// ---------------------------
// 你也可以改用更细粒度的 primitives 自定义外观；此处采用 @assistant-ui/react-ui 的 Thread 组件。

export default function App() {
  // 你可通过 URL 参数或路由传入 threadId 等信息（示例保留默认主线程）。
  const header = useMemo(
    () => (
      <div className="border-b bg-background/60 backdrop-blur supports-[backdrop-filter]:bg-background/60">
        <div className="mx-auto max-w-3xl px-4 py-3">
          <div className="text-sm opacity-70">LangGraph Agent · FastAPI · Streaming</div>
          <h1 className="text-lg font-semibold">assistant-ui × LangGraph(FastAPI) 演示</h1>
        </div>
      </div>
    ),
    []
  );

  return (
    <div className="h-screen w-full flex flex-col">
      {header}
      <div className="mx-auto max-w-3xl w-full grow px-4">
        <div className="h-full py-4">
          <AssistantProvider>
            {/* 注册前端 Tool UI（顺序无关，可按需增减；未注册的工具将 fallback 到纯文本或你自定义的 ToolFallback）*/}
            <WebSearchToolUI />
            <FetchUrlToolUI />
            <PythonToolUI />

            {/* 线程组件：包含消息视图 + 输入框，默认支持 Markdown、高亮、附件、撤回/编辑、自动滚动等 */}
            <Thread className="h-full rounded-2xl border" placeholder="问我任何问题，或让代理调用工具…" />
          </AssistantProvider>
        </div>
      </div>
    </div>
  );
}

// ------------------------------------------------------------
// 4) 与 FastAPI/LangGraph 的接口契约（仅供参考，非前端代码）
// ------------------------------------------------------------
// FastAPI 需要在 /api/chat 接收形如 { messages: UIMessage[] } 的 JSON，并返回 SSE：
//   Content-Type: text/event-stream
//   x-vercel-ai-ui-message-stream: v1
// 核心事件示例（每行以 `data: <json>\n\n` 形式发送；最后 `data: [DONE]\n\n` 终止）：
//   data: {"type":"start","messageId":"..."}
//   data: {"type":"text-start","id":"..."}
//   data: {"type":"text-delta","id":"...","delta":"Hello"}
//   data: {"type":"text-end","id":"..."}
//   data: {"type":"tool-input-start","toolCallId":"...","toolName":"python"}
//   data: {"type":"tool-input-delta","toolCallId":"...","inputTextDelta":"print(1)"}
//   data: {"type":"tool-input-available","toolCallId":"...","toolName":"python","input":{"code":"print(1)"}}
//   data: {"type":"tool-output-available","toolCallId":"...","output":{"stdout":"1\n"}}
//   data: {"type":"finish-step"}
//   data: {"type":"finish"}
//   data: [DONE]
// 这些事件可由 LangGraph 的 streaming 回调/事件（如 on_event/on_tool_start/on_tool_end）转换而来。

```

# 怎么用

1. 安装依赖

```bash
npm i @assistant-ui/react @assistant-ui/react-ui @assistant-ui/react-data-stream \
      @assistant-ui/react-markdown remark-gfm @radix-ui/react-tooltip \
      @radix-ui/react-slot lucide-react class-variance-authority clsx tailwindcss-animate
```

2. 加样式

* `tailwind.config.ts` 添加：

  ```ts
  plugins: [
    require("tailwindcss-animate"),
    require("@assistant-ui/react-ui/tailwindcss")({ components: ["thread","thread-list"], shadcn: true })
  ]
  ```
* 在全局布局（如 `app/layout.tsx`）里加入：

  ```ts
  import "@assistant-ui/react-ui/styles/index.css";
  ```

3. 放代码
   把我提供的文件作为 `app/page.tsx`（或你的任意页面组件）使用即可。

4. 与后端的对接约定（FastAPI + LangGraph）

* 前端默认向 `POST /api/chat` 发送 `{ messages: UIMessage[] }`，并期望 **SSE** 流式返回，协议为 **Vercel AI SDK 的 Data Stream 协议**：响应头 **必须** 包含 `x-vercel-ai-ui-message-stream: v1`。
* 你的 FastAPI 需要把 LangGraph 的运行/工具事件映射为以下事件并逐条写出（SSE `data:` 行，一行一个 JSON，末尾 `[DONE]` 终止），例如：

  * `start`、`text-start` / `text-delta` / `text-end`
  * `tool-input-start` / `tool-input-delta` / `tool-input-available`
  * `tool-output-available`
  * `start-step` / `finish-step`、`finish`、`[DONE]`

画布代码里我已注册了常见工具 UI（`web_search`、`fetch_url`、`python`），多步/工具调用会自动以卡片形式流式显示、并和模型文本交替渲染。

# 关键参考（确认兼容性）

* assistant-ui 官方入门与组件：([assistant-ui.com][1])
* 预置样式包与示例 Thread 用法：([assistant-ui.com][2])
* Data Stream 运行时（前端）与 API：([assistant-ui.com][3])
* Data Stream 协议（后端需要按此协议推送 SSE）：事件清单与 `x-vercel-ai-ui-message-stream: v1` 头要求见 ([AI SDK][4])
* LangGraph/assistant-ui 官方整合说明与示例：([assistant-ui.com][5], [LangChain Blog][6])

如果你愿意，我也可以给你一份最小可用的 FastAPI 端 `/api/chat` 实现（把 LangGraph 的事件转成 Data Stream 协议 SSE），直接贴到你服务里就能和前端对上。

[1]: https://www.assistant-ui.com/docs?utm_source=chatgpt.com "Getting Started"
[2]: https://www.assistant-ui.com/docs/legacy/styled/Thread "Thread | assistant-ui"
[3]: https://www.assistant-ui.com/docs/api-reference/integrations/react-data-stream?utm_source=chatgpt.com "assistant-ui/react-data-stream"
[4]: https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol "AI SDK UI: Stream Protocols"
[5]: https://www.assistant-ui.com/docs/runtimes/langgraph?utm_source=chatgpt.com "Getting Started"
[6]: https://blog.langchain.dev/assistant-ui/?utm_source=chatgpt.com "Build stateful conversational AI agents with LangGraph and ..."