概览

基于 LangChain Agent 的实时流构建生成式 UI

为使用 createAgent 创建的 Agent 构建丰富、可交互的前端。这些模式涵盖了从基础消息渲染到高级工作流（如人在回路审批、排队提交、持久流重新接入以及时间旅行调试）的所有内容。

LangChain 前端 SDK 专为智能体应用（agent applications）打造，而不仅仅是 Token 流式传输聊天机器人。用于渲染消息的同一个 Hook，也暴露了 Agent 的持久线程状态、工具调用生命周期、中断、检查点历史以及自定义状态值，因此你的 UI 可以成为长时间运行的 Agent 任务的控制面板。

NOTE

这些模式使用了 v1 前端 SDK 包。如果你使用的是早期版本，请参阅适用于 React、Vue、Svelte 和 Angular 的迁移指南。

架构

每个模式都遵循相同的架构：createAgent 后端通过 SDK 流式 API（stream API）将状态流式传输到前端。

在后端，createAgent 会生成一个编译好的 LangGraph 图并暴露流式 API。在前端，流句柄连接到该 API 并提供响应式状态——消息、工具调用、中断、状态值（values）以及线程元数据——你可以使用任何框架来渲染它们。

为什么使用 LangChain 前端 SDK？

大多数 AI UI 库仅帮助你将流式文本追加到聊天记录中。LangChain 的 SDK 则暴露了生产级 Agent 所需的更丰富的运行时语义：

能力	在 UI 中实现的功能
持久线程 (Durable threads)	刷新页面、切换设备或重新加入运行，而不会丢失对话状态。
类型化 Agent 状态 (Typed agent state)	渲染任何状态键，不仅限于消息：待办事项（todos）、流水线输出、引用、沙箱文件、指标或自定义业务对象。
工具调用生命周期 (Tool-call lifecycle)	将进行中、已完成和失败的工具调用显示为专门构建的 UI 卡片，而不是原始 JSON。
中断 (Interrupts)	暂停执行以等待人工审批、编辑或补充缺失信息，然后从 Agent 停止的确切位置恢复执行。
检查点 (Checkpoints)	基于持久化的状态快照构建编辑、重试、分支、审计和时间旅行流程。
嵌套执行 (Nested execution)	可视化深层 Agent（deep agents）、子 Agent（subagents）和图节点，而无需将所有内容展平为单条难以阅读的流。
框架原生响应式 (Framework-native reactivity)	在 React、Vue、Svelte 或 Angular 中使用相同的协议，同时保留各框架符合习惯的 Hook、Composable、Store 或 Signal。

这些原语让你可以设计出允许用户在 Agent 工作进行时对其进行检查、引导、暂停、恢复和分叉的 UI。

agent.tsChat.tsx

import { createAgent } from "langchain";
import { MemorySaver } from "@langchain/langgraph";

const agent = createAgent({
  model: "openai:gpt-5.5",
  tools: [getWeather, searchWeb],
  checkpointer: new MemorySaver(),
});

tsx

import { useStream } from "@langchain/react";
import type { agent } from "./agent";

function Chat() {
  const stream = useStream<typeof agent>({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
  });

  return (
    <div>
      {stream.messages.map((msg) => (
        <Message key={msg.id} message={msg} />
      ))}
    </div>
  );
}

React、Vue 和 Svelte 使用 useStream。Angular 使用 injectStream：

import { useStream } from "@langchain/react";      // React
import { useStream } from "@langchain/vue";        // Vue
import { useStream } from "@langchain/svelte";     // Svelte
import { injectStream } from "@langchain/angular"; // Angular

类型推断

向 useStream（或 Angular 中的 injectStream）传递类型参数，以类型安全地访问 stream.messages、stream.toolCalls、stream.interrupt、stream.values 以及其他响应式状态。

导入你的 Agent 并将 typeof myAgent 作为类型参数传入。TypeScript 会从编译后的图中推断出状态模式（state schema）：

import type { myAgent } from "./agent";

const stream = useStream<typeof myAgent>({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",
});

自定义状态键会自动推断，无需手动定义接口。

模式

渲染消息与输出

Markdown 消息
解析并渲染流式 Markdown，支持规范的排版与代码高亮。

结构化输出
将类型化的 Agent 响应渲染为自定义 UI 组件，而不是纯文本。

推理 Token
在可折叠块中展示模型的思考过程。

生成式 UI
渲染由 Agent 生成的界面，涵盖受控式（controlled）、声明式（declarative）到开放式（open-ended）的全维度。

展示 Agent 操作

工具调用
将工具调用展示为丰富且类型安全的 UI 卡片，并带有加载中与错误状态。

无头工具
在客户端上运行浏览器与设备 API，同时在 Agent 端保持类型化的工具模式（tool schemas）。

人在回路
暂停 Agent 执行以进行人工审核，支持审批、驳回和编辑工作流。

管理会话

分支对话
编辑消息、重新生成回复并在会话分支之间切换。

消息队列
将多条消息排入队列，由 Agent 依次按序处理。

高级流式传输

加入与重新加入流
断开连接并重新连接到正在运行的 Agent 流，而不会丢失进度。

时间旅行
检查、浏览并从会话历史记录中的任意检查点恢复执行。

选择前端模式

从你的应用程序需要解答的 UX 问题入手：

如果用户需要...	从这里开始
了解 Agent 正在执行什么操作	工具调用和推理 Token
安全地审批敏感操作	人在回路
在某次运行处于活跃状态时发送任务	消息队列
离开并在稍后返回长时间运行的任务	加入与重新加入流
编辑或从较早的轮次重试	分支对话和时间旅行
将状态渲染为应用程序而非聊天	结构化输出、生成式 UI 和 Deep Agents 前端模式

集成

流式 API 与 UI 无关。你可以将其与任何组件库或生成式 UI 框架配合使用。组件库可以负责展现层，而 LangChain 的 SDK 则在底层负责 Agent 运行时状态、可恢复性、中断以及检查点语义。

AI Elements
用于 AI 聊天的可组合 shadcn/ui 组件：Conversation、Message、Tool、Reasoning。

assistant-ui
具备内置线程管理、分支以及附件支持的无头（Headless）React 框架。

OpenUI
使用 openui-lang 组件 DSL 构建富数据报告和仪表盘的生成式 UI 库。

概览 ​

架构 ​

为什么使用 LangChain 前端 SDK？ ​

类型推断 ​

模式 ​

渲染消息与输出 ​

展示 Agent 操作 ​

管理会话 ​

高级流式传输 ​

选择前端模式 ​

集成 ​

概览

架构