目录

• 1. 不只是聊天机器人
• 2. 统一架构与状态五件套
• 3. 六大能力逐条拆解
• 4. useStream 钩子的中心地位
• 5. 四框架支持矩阵
• 6. 两大模式组与板块地图
• 7. 连接的标配
• 8. 边界与常见坑
• 总结
• 外部引用

摘要

官方前端 SDK 把 agent 的后端状态持续流向前端，一个钩子同时暴露消息、工具调用与检查点历史。本文拆解统一架构、六大能力、useStream 写法与四框架矩阵，并给出 51 到 60 篇的板块地图。读完你能判断自己的界面缺哪块能力，以及该先看哪一页官方文档。

1. 不只是聊天机器人

后端把 agent 跑通之后，下一件事是给它一张可用的脸。官方文档的前端板块在导航里有约 20 页。范围从最基础的 Markdown 消息渲染，一直排到时间旅行调试。入口 overview 页给了一句定位句，这句话决定了整个板块应该怎么读。

1.1 官方定位句拆解

官方 overview 页的关键原话如下。

LangChain frontend SDK 为 agent 应用而生，不只是 token 流聊天机器人。渲染消息的同一个 hook，也暴露 agent 的持久线程状态、工具调用生命周期、中断、检查点历史与自定义状态值——UI 可以成为长运行 agent 工作的控制平面。

这句话拆成两半看。前半句划清边界：这套 SDK 的对象是 agent 应用，不是通用聊天组件。后半句给出机制：消息渲染与状态暴露来自同一个 hook（钩子，框架里把外部数据接进组件、数据一变界面自动更新的函数）。

控制平面（control plane）这个词需要一句白话。先类比：飞机座舱里乘客位只负责看电影，驾驶位负责油门、舵面和仪表。聊天界面是乘客位，控制平面是驾驶位。你不只看 agent 说了什么，还能对它正在做的事下手。

下表把两种视角摆在一起。左边是聊天机器人 SDK 的默认假设，右边是 agent 前端 SDK 的实际供给。

维度	聊天机器人视角	agent 控制平面视角
渲染对象	token 流拼出的文本	messages 等五件套状态
交互模型	发一条收一条	审批、编辑、重试、排队提交
状态存活	刷新页面即丢	持久线程，跨设备重连不丢
界面定位	展示层	控制平面

概念上两层的关系如下图。下半环是传统聊天路径，上半环是控制平面路径，两条路径共用同一条状态流。

图里的关键是回环。控制平面的每次操作都沿原路写回后端，驱动 agent 继续执行，而不是刷新整个会话。这就是渲染消息的同一个 hook 能兼任控制职责的原因。

1.2 后端开发者为何要看前端板块

官方对板块的定位原文是：为 createAgent 构建的 agent 打造富交互前端。模式覆盖从基础消息渲染到高级工作流，官方点名了四类高级工作流：human-in-the-loop 审批、排队提交、持久流重连、时间旅行调试。

对后端开发者来说，这里有一条朴素的事实。你在后端实现的中断、检查点、线程持久化，如果前端没有对应入口，用户就摸不到这些能力。机制等于只做了一半。

界面因此是 agent 的驾驶舱，不是外包装。驾驶舱缺一块仪表，对应的后端能力在产品里就等于不存在。反过来，前端板块的每个模式页，都是某块仪表的接线说明书。

数字上先给一个概览。Patterns 组有 10 个模式页，Generative UI 组有 4 个页，两组合计 14 个模式页。加上总览与索引页，板块整体约 20 页。第 6 章会把这 20 页摊成一张地图。

再看一个成本视角。后端开发者补前端板块的边际成本偏低，因为概念你已经全有了。中断、检查点、线程、工具调用这些词在后端篇里都出现过。板块做的事只是把它们接到界面上。

后端已有的概念	前端板块对应页	补的是哪块
中断与恢复	Human-in-the-Loop	审批界面与恢复入口
检查点历史	Time travel、Branching chat	历史浏览与分叉操作
线程持久化	Join & rejoin streams	断线重连与会话切换
工具注册	Tool calling、Headless tools	工具卡片与自定义操作

表里左列是你已经写过的代码，右列是还没写的界面。中间那列就是阅读清单，按项目当前缺哪块挑哪块。

还有一个时间维度的判断。如果 agent 还处在验证阶段，只有你自己在用，Studio 够用，前端板块可以往后放。一旦要交给第二个人用，板块里的模式就开始变现了。

阅读策略只有一条：先读本文建立骨架，再按地图挑当前最需要的一页深入。不要按导航顺序从第一页啃到最后一页，那样会在第 3 页就失去耐心。

这 20 页模式再多，底下跑的都是同一套架构。第 2 章拆这条主干。

2. 统一架构与状态五件套

overview 页明确说，每个模式遵循同一架构：createAgent 后端经 SDK stream API 把状态流向前端。这句话两头各站着一个角色，后端侧是一张编译好的图，前端侧是一个 stream 句柄。本章分别拆开。

2.1 后端侧一张编译图自带流式 API

后端侧的官方原文是：createAgent 产出暴露流式 API 的已编译 LangGraph 图。已编译图（compiled graph）指完成组装、可以直接执行的图对象。它不再是待定义的描述，而是可运行、可流式读取的服务单元。

这一点对后端开发者是个减负消息。你不需要为前端再写一层接口服务，createAgent 给你的图本身就带流式 API。前端的每个请求，最终都落在图暴露的这组接口上。

# 来源：自实现 / 演示脚本
# 后端侧最小形态：create_agent 产出已编译的 LangGraph 图
agent = create_agent(
    model="openai:gpt-5",   # 模型标识，按项目实际填写
    tools=[search_docs],    # 工具列表，前端会看到每次调用的生命周期
)

# create_agent 返回的对象自带流式 API
# 前端 stream 句柄连接的就是这组接口，不需要额外包一层服务
for chunk in agent.stream(inputs, stream_mode="values"):
    print(chunk)

这段代码做两件事。create_agent 组装并返回已编译图。tools 参数里的每个工具都会以生命周期事件的形式流向前端。下面的 stream 调用只是证明接口在图上，不是要你在后端手动消费它。

整条链路的结构如下图，从左到右是后端到前端的完整路径。

图里没有第五个节点之前，一切都停留在后端。流式 API 是唯一的出口，前端句柄是唯一的进口，中间不存在第二条通道。模式页的所有花样都发生在最右侧的渲染层。

2.2 前端侧 stream 句柄与响应式状态五件套

前端侧的官方原文是：stream 句柄连接该 API 并提供响应式状态——messages、tool calls、interrupts、values、thread metadata——用任何框架渲染。句柄（handle）就是握在组件手里的那个连接对象，响应式状态（reactive state）指数据一变界面自动重渲染。

五件套的每一件都对应一块界面职责。下表逐项列出。

状态	内容	典型界面用途
messages	对话消息，含流式增量	消息列表与打字机效果
tool calls	工具调用数组，含各自生命周期	工具卡片、进度与结果展示
interrupts	中断事件，等待人工处理	审批弹窗、补充信息表单
values	任意状态键，不止 messages	业务面板，如 todos 与指标
thread metadata	线程元信息	线程列表、会话切换

五件套的形状可以用一段类型示意表达。字段名以官方 API 参考为准，第 4 章给出确切写法。

// 来源：自实现 / 演示脚本
// stream 句柄提供的响应式状态，概念形状示意
type StreamState = {
  messages: Message[];              // 对话消息，含流式增量
  toolCalls: ToolCall[];            // 工具调用数组，含各自生命周期
  interrupts: Interrupt[];          // 中断事件，等待人工处理
  values: Record<string, unknown>;  // 任意状态键，不止 messages
  threadMetadata: Record<string, unknown>; // 线程元信息
};

// values 是承载面最宽的一件，官方点名的可渲染内容包括
type ValueKeys = {
  todos: Todo[];                    // 待办清单
  pipelineOutput: PipelineResult;   // 管线输出
  citations: Citation[];            // 引用列表
  sandboxFiles: string[];           // 沙箱文件
  metrics: Record<string, number>;  // 指标
};

这段类型把官方那句话翻译成了前端语言。关键在 values 一行：它是任意状态键的容器。todos、管线输出、引用、沙箱文件、指标都能装进来。messages 只是最常用的一个键，不是全部。第二段类型列出官方点名的可渲染键，界面面板直接从这里面挑。

架构统一带来一个直接后果：学一次五件套，所有模式页都能读懂。模式与模式之间的差别只在消费哪几件状态、渲染成什么组件。

五件套里最有产品味的几件，官方单独整理成了一张能力表。第 3 章逐条拆它。

3. 六大能力逐条拆解

overview 页的能力表列了六项。前五项官方给了完整描述，第六项在表格中途截断。本节按已核实的原文呈现，截断处明确标注以官方页为准。

3.1 官方能力表逐条白话

先用一句大白话过一遍，再给官方描述。这六件事合起来，把一个聊天框升级成能被驾驶的工作台。

能力	官方描述要点	一句大白话
Durable threads 持久线程	刷新页面、切换设备、重连运行都不丢对话状态	换台电脑回来，话还接着说
Typed agent state 类型化状态	渲染任意状态键而不只是 messages	界面想显示啥就显示啥，不止聊天记录
Tool-call lifecycle 工具调用生命周期	pending、completed、failed 显示为专门 UI 卡片而不是原始 JSON	工具调用像快递一样有在途、签收、失败三态
Interrupts 中断	暂停执行等人批准、编辑或补信息，然后从停下的精确位置恢复	agent 遇事不擅自行动，先问你
Checkpoints 检查点	构建 edit、retry、branch	改历史、重试旧路、分叉新路
自定义状态值	属于状态化渲染范围，与类型化状态同源	业务对象直接进界面

第五项 Checkpoints 的官方表格在 branch 之后被截断，后续能力描述以官方页为准，链接见外部引用第一条。这里只保留已确认的文字，不往下补。

三态生命周期能力值得单独展开，因为它最容易在前端被做坏。官方明确要求的是专门 UI 卡片，而不是把原始 JSON 糊给用户。

// 来源：自实现 / 演示脚本
// 工具调用三态的界面分支示意
function ToolCard({ call }: { call: ToolCall }) {
  if (call.status === "pending") {
    return <Card>正在调用 {call.name}…</Card>;      // pending 阶段给进度提示
  }
  if (call.status === "completed") {
    return <Card>{call.name} 完成</Card>;             // completed 阶段展示结果摘要
  }
  return <Card>{call.name} 失败</Card>;               // failed 阶段给出可理解的错误
}

// 消费侧：从同一个 stream 上取工具调用数组，逐个渲染卡片
function ToolPanel({ stream }: { stream: StreamHandle }) {
  return (
    <div>
      {stream.toolCalls.map((call) => (
        <ToolCard key={call.id} call={call} />
      ))}
    </div>
  );
}

这段代码做的是把三态映射成三种卡片。关键行为是每个分支都面向使用者语言，而不是面向调试者语言。下半段给出消费侧写法：卡片数组来自同一个 stream，不需要为工具面板单开一条连接。JSON 透传是这一能力的失败形态，第 8 章会把它列进坑表。

六大能力与五件套的覆盖关系如下图。左侧是能力，右侧是它主要依赖的状态件。

图里三个能力同时指向 values，说明 values 是承载面最宽的一件状态。中断与工具调用生命周期则各有专属状态件，界面处理起来路径最短。

3.2 能力与后端机制的对应

这六项前端能力没有一项是空中楼阁，每一项都对应一篇后端机制。后端没铺好对应机制，前端能力就没有数据来源。下表给出映射，篇号为系列内既有篇目。

前端能力	对应后端机制	后端篇目
Interrupts 中断	graph.interrupt 的实现与恢复	第 26 篇、第 34 篇
Checkpoints 检查点	checkpointer 与历史读取	第 43 篇
Durable threads 持久线程	线程与持久化存储	第 43 篇
Typed agent state 类型化状态	图的状态模式定义	以官方文档为准
Tool-call lifecycle 工具调用生命周期	工具节点的事件输出	以官方文档为准
自定义状态值	状态键的读写约定	以官方文档为准

表里后三行没有对应的既有篇目，属于本系列后端板块未覆盖的部分，细节以官方文档为准。

映射的实用价值在排障。界面上某个能力不工作，先查这张表，再去后端确认机制是否真的存在。比如中断弹窗从不出现，问题大概率不在前端组件，而在后端图里没安排中断点。

把这张表用在阅读上也有效。官方每个模式页开头都会写前置条件，说明它依赖哪个后端机制。拿着本篇的映射表去比对，能提前判断某个模式在你的项目里能不能直接跑。

四条供给链可以这样理解。状态模式定义产出可用状态键。中断点安排产出 interrupts 事件。checkpointer 配置产出检查点历史。工具注册产出 tool calls 事件。任何一条链的左端缺失，右端界面就只能拿到空值。

后端开发者还有一个反向收益。看前端模式页能帮你发现后端能力的盲区。比如你从没配过 checkpointer，那么 Branching chat 与 Time travel 两页对你就是纯理论。先回第 43 篇补机制再回来。

排障顺序可以固定成三步。第一步看后端机制是否存在，第二步看状态是否真的流到了前端，第三步才动界面组件。三步对应的检查点分别是图定义、stream 状态对象、组件渲染分支。

// 来源：自实现 / 演示脚本
// 排障三步的取数侧验证：先确认状态到了，再怀疑组件
function DebugPanel({ stream }: { stream: StreamHandle }) {
  console.log("messages", stream.messages.length);    // 步骤二 消息是否到达
  console.log("toolCalls", stream.toolCalls.length);   // 步骤二 工具事件是否到达
  console.log("interrupts", stream.interrupts.length); // 步骤二 中断是否到达
  console.log("values keys", Object.keys(stream.values)); // 步骤二 状态键有哪些
  console.log("thread", stream.thread);                // 步骤二 线程信息是否到达
  return null;                                         // 只做诊断，不渲染界面
}

这段代码是三步里的第二步。把它临时挂进界面，能立刻区分问题在链路还是在组件。五件套的到达情况一次打全，覆盖 messages、toolCalls、interrupts、values、thread。三个数字都是零，回第一步查后端；数字正常但界面空白，进第三步查渲染分支。

六大能力从后端流到前端，需要一个统一的取数入口。官方把这个入口做成了一个 hook，第 4 章讲它。

4. useStream 钩子的中心地位

官方 tool-calling 页等处的表述是：useStream 连接 agent 后端，返回含 toolCalls 数组的响应式状态。它是多数模式的核心。

4.1 一个钩子拿到全部状态

useStream（一个把后端流接进组件、返回响应式状态的 React 钩子）的职责可以拆成两半。前一半是连接：指向 agent 后端地址，绑定一个线程。后一半是取数：把五件套变成组件可直接读取的响应式值。

模式页示例的标配写法长这样。AGENT_URL 与 assistantId 的取值说明见第 7 章。

// 来源：LangChain 官方文档 / frontend 模式页示例形态
const stream = useStream({
  apiUrl: AGENT_URL,                  // agent 后端地址，本地默认 2024 端口
  assistantId: ASSISTANT_ID,          // 要连接的 agent 标识
});

// 响应式状态：不止 messages
// 字段名以 useStream API 参考为准，此处按官方模式页示例形态列示
stream.messages      // 对话消息
stream.toolCalls     // 工具调用数组，含 pending completed failed
stream.interrupts    // 中断事件，等待人工处理
stream.values        // 任意状态键，不止 messages
stream.thread        // 线程元信息

// 消息区只消费 messages，业务面板只消费 values，互不干扰
function MessageList() {
  return stream.messages.map((m) => <p key={m.id}>{m.content}</p>);
}

这段代码是整个板块的取数范式。关键在最后一组读取：官方 tool-calling 页明确说返回状态里含 toolCalls 数组。也就是说工具卡片不需要第二个连接。界面组件从同一个 stream 对象上各取所需，这是渲染与控制共用一个 hook 的具体实现。字段确切名称以 useStream API 参考为准。

取数路径如下图，一个句柄分出五路状态。

图里从 B 到 C 只发生一次连接。如果界面需要在多处消费状态，共享的是同一个响应式对象，而不是各自再开一条流。

4.2 类型安全写法与类型推断入口

官方模式页给出的类型安全写法是 useStream。含义是：用后端 agent 的类型作为泛型参数。前端拿到的 values 就是后端状态模式的形状，不再需要手写一遍类型。

// 来源：LangChain 官方文档 / frontend 模式页示例形态
type MyAgent = typeof myAgent;        // 取后端 agent 的类型

const stream = useStream<MyAgent>({
  apiUrl: AGENT_URL,
  assistantId: ASSISTANT_ID,
});

// values 的形状来自后端状态模式，编辑器可自动补全
stream.values.todos                  // 类型来自后端定义
stream.values.pipelineOutput         // 不存在拼错键名也能被编译器拦下

// 不写泛型参数时的对照，问题在这里暴露
const loose = useStream({
  apiUrl: AGENT_URL,
  assistantId: ASSISTANT_ID,
});

loose.values.toodos                  // 拼错键名，编译器无感，运行时拿到 undefined

这段代码的关键是泛型参数。写上它，前端类型与后端状态模式保持同源；不写它，values 退化为宽泛类型，拼写错误只能在运行时暴露。

类型如何从 Python 后端流到 TypeScript 前端，官方提供了 Type inference（类型推断）机制。它对 Python 与 JavaScript 后端各有独立入口。两条入口的配置细节不在本篇范围内，以官方文档为准，链接见外部引用第一条与第二条。

类型链路的两个分支如下图，分支取决于你的后端语言。

图里两条分支在 E 汇合，说明无论后端语言是哪种，前端侧的最终形态一致。这也解释了为什么四框架文档可以共用同一套示例逻辑。

useStream 的写法在四个框架里各有一份对应实现。第 5 章把支持情况排成矩阵。

5. 四框架支持矩阵

官方前端文档的每个示例页都带四个框架标签页：React、Vue、Svelte、Angular。这一事实比任何宣传语都直接，四个主流框架是一等公民。

5.1 四框架全支持的事实形态

在官方模式页上，同一份示例逻辑会以四个标签的形式并排出现。你切换标签，看到的业务代码一致，只是框架语法不同。这意味着选型可以完全按团队既有技术栈走，不需要为了这套 SDK 换框架。

维度	React	Vue	Svelte	Angular
官方模式页示例	有	有	有	有
useStream 等价钩子	有	有	有	有
v1 SDK 包	有	有	有	有
迁移指南文档	有	有	有	有

表里四列全部打勾，来源是官方页面每例四标签这一事实。各框架钩子的确切名称与签名存在差异，不在此处猜测。以 useStream API 参考与各框架迁移文档为准，链接见外部引用第二条与第五条。

同一逻辑在四个框架下的结构对齐关系如下图。

图里四条支路最终汇到同一个后端。这也是第 2 章统一架构的另一种体现：框架差异被限制在最外层渲染，不侵入取数与控制逻辑。

切换标签时值得留意一件事：四个标签页里的 AGENT_URL、assistantId 与 stream 字段名是一致的。变化的只有组件声明方式与响应式绑定的语法。这意味着后端接口设计一旦确定，换框架的迁移成本主要在组件层，不在数据层。

对团队选型还有一个实际推论。四个框架的示例同时存在，等于官方替你做了交叉验证。同一个 agent 后端，四个框架都能接。技术评审时不需要担心框架兼容性成为阻塞项，可以直接按招聘市场与既有代码库决定。

5.2 v1 SDK 与迁移指南

官方 overview 明确：模式用 v1 前端 SDK 包。也就是说，你在模式页看到的示例代码，默认建立在 v1 包的基础上。

如果项目里已有旧版本前端 SDK，官方的建议是看迁移指南。React、Vue、Svelte、Angular 四个框架各有独立迁移文档。它们统一放在 GitHub 的 langgraphjs 仓库里。

# 来源：自实现 / 演示命令
# 获取 v1 迁移指南的入口
# 四个框架的迁移文档都在 langgraphjs 仓库内
open https://github.com/langchain-ai/langgraphjs

# 迁移前先确认项目里当前的包版本，再挑对应框架的文档
# npm 项目看 package.json 里的依赖版本行
grep -n "langchain" package.json

# 锁文件存在时再看一条，确认实际安装的版本
grep -n "langchain" package-lock.json | head -5

# 具体安装命令、包名与版本号以官方迁移文档为准，此处不猜测

这段命令做两件事。第一组打开迁移指南的仓库入口，四份框架文档都在里面。第二组帮你确认现状，迁移文档通常按起始版本分段，先知道自己在哪一段。包名与版本号随版本变化，写在本文里会很快过期，以仓库内文档为准。

版本演进路径如下图，重点是右侧的分叉处理。

图里新项目与旧项目在 C 和 D 处分流，四份迁移文档最后都指向 v1。判断自己走哪条路，只看项目里现在装的是哪个版本。

框架问题解决后，剩下的是选模式。第 6 章把 20 页摊成地图。

6. 两大模式组与板块地图

官方导航把前端板块的模式页分成两组：Patterns 与 Generative UI。两组的分工很清楚，Patterns 解决交互结构，Generative UI 解决界面生成方式。

6.1 Patterns 十式清单

Patterns 组共 10 个模式页，导航已核实。下表每式一句话，先给定位再谈取舍。

模式页	一句话定位
Markdown messages	消息以 Markdown 渲染，代码块与列表可用
Tool calling	工具调用以卡片形式展示三态生命周期
Structured output	模型输出按结构化模式呈现与校验
Headless tools	只取工具状态不取模型输出，界面自定操作
Branching chat	从任一检查点分叉出新对话分支
Message queues	输入先排队，agent 空闲后再依次提交
Join & rejoin streams	多端加入同一线程流，断开后可重连
Time travel	回到历史检查点查看并恢复执行
Reasoning tokens	展示模型的推理过程 token
Human-in-the-Loop	关键动作前中断，等待人工审批

十式之间存在明显的难度梯度。前四式围绕渲染，中间四式围绕流与历史的操控，最后两式回到人工介入。这个梯度也大致是建议的阅读顺序。

十式的分层关系如下图，自下而上是能力叠加的方向。

图里五层是叠加关系，不是替代关系。做审批界面时下面四层通常已经在用，人工层是最后补上的那一块。

6.2 Generative UI 光谱预告

Generative UI（生成式界面，由模型按需生成界面组件而非纯文本回复）组共 4 页。分别是总览、Controlled、Declarative、Open-ended。光谱的三个档位可以这样区分。

档位	一句话定位
Controlled 受控	界面组件由你定义，模型只能在白名单里选
Declarative 声明式	用声明式配置描述界面，模型按配置生成
Open-ended 开放式	界面结构完全交给模型按需生成

三个档位是一条控制权光谱。从左到右，你对界面的掌控递减，模型自由度递增。安全与可预测性沿同一方向递减，灵活性与惊喜感沿同一方向递增。这一光谱将在第 52 到 54 篇逐档展开。

光谱上还有一个容易忽略的事实：三档不是三选一的立场声明。同一个界面里可以混用。操作类按钮用 Controlled 保稳定，展示类卡片用 Declarative 提效率。

把两组合起来，整个板块约 20 页的全景如下。

图里两组并列，不存在先后依赖。你可以先做 Patterns 再碰 Generative UI，也可以反过来。

地图有了，下一步是接线。第 7 章讲连接后端的标配。

7. 连接的标配

模式页示例里反复出现两个常量：AGENT_URL 与 assistantId。前者是后端地址，后者是 agent 标识。这一章把它们与本地开发流程的关系讲清楚。

7.1 AGENT_URL 与 langgraph dev

官方 tool-calling、branching 等页的示例里，AGENT_URL 常量取值固定为 http://localhost:2024。2024 是本地开发的默认端口。前端所有请求都指向这里。

// 来源：LangChain 官方文档 / frontend 模式页示例事实
const AGENT_URL = "http://localhost:2024";   // 本地 agent 后端默认端口
const ASSISTANT_ID = "agent";                 // 要连接的 agent 标识

// 前端取数处统一引用这两个常量，避免地址散落多处
const stream = useStream({
  apiUrl: AGENT_URL,         // 指向本地 Agent Server
  assistantId: ASSISTANT_ID, // 决定请求路由到哪个 agent
});

// 换环境只改这一处，组件代码不动
export { AGENT_URL, ASSISTANT_ID, stream };

这几行是前端连接的最小配置。AGENT_URL 指向本地 LangGraph Agent Server。assistantId 决定请求落到哪个 agent 上。下面把常量集中定义、取数处统一引用。换环境时只改一处。

要把 2024 端口跑起来，靠的是 langgraph dev。官方 branching 等页明确要求 Agent Server 在运行。LangGraph Agent Server 是本地起的 agent 服务，负责把你的图以流式 API 形式暴露出来。

# 来源：自实现 / 演示命令
# 本地启动 Agent Server，前端示例默认连它的 2024 端口
langgraph dev

# 起来之后前端 AGENT_URL 保持 http://localhost:2024 即可
# 浏览器先访问一次本地服务地址，确认端口已监听
open http://localhost:2024

# 端口没响应时先查进程，判断是没启动还是崩了
# Windows 下换用 tasklist 查看进程列表
ps aux | grep -i langgraph

# 其他启动参数与配置项以官方 local-server 文档为准

这段命令是本地开发的主开关。第一条启动服务，第二条用浏览器确认端口已经监听。第三条在端口无响应时区分没启动与崩溃两种情况。它没起来，前端页面上所有请求都会失败，这是新手最常见的第一个报错来源。

完整的连接链路如下图，从前端常量到后端图。

图里 assistantId 从旁路进入 Agent Server，决定请求路由到哪个 agent。AGENT_URL 只管地址，不管路由，两件事分开配置。

7.2 与 Studio 的关系

第 46 篇讲过 LangGraph Studio。这里的关键事实是：Studio 与本板块的前端连的是同一个本地 Agent Server。也就是说，langgraph dev 起来的那个 2024 端口，同时服务两种消费方。

维度	LangGraph Studio	本板块自建前端
性质	官方提供的现成界面	你自己写的应用界面
连接对象	本地 Agent Server	同一个本地 Agent Server
定制程度	固定，按官方设计	完全自定
适用阶段	开发调试与图检查	交付给用户的最终界面

两者的分工由此清楚。开发期用 Studio 检查图的行为与状态流转，交付期用自建前端承载产品交互。工具不是二选一，是先后两步。

两种消费方与同一服务器的关系如下图。

图里 B 与 C 是并列的两条消费路径，指向同一个 A。在 Studio 里看到的状态，就是你自建前端将要收到的状态，这给联调提供了一个免费的参照物。

连接跑通只是及格线。第 8 章列出最常见的失败形态与板块的阅读路线。

8. 边界与常见坑

本章把前面各章的事实收进一张对照表，再给一条 51 到 60 篇的阅读路线。这是本系列的板块开篇，路线图本身就是交付物之一。

8.1 失败模式对照表

四类坑在实践里出现频率最高。每一类都有明确的事实来源与解法指向。

失败模式	典型表现	事实依据与解法指向
拿聊天 SDK 硬接 agent 流	只能渲染文本，工具卡片与审批都做不了	官方定位句明确 SDK 为 agent 应用而生，不止 token 流
忘起 Agent Server 连不上	前端请求全部失败或超时	langgraph dev 需 Agent Server，官方 branching 等页明确要求
只用 messages 丢掉其他状态	界面只剩聊天气泡，业务面板空白	五件套还包括 tool calls、interrupts、values、thread metadata
Type inference 没配导致 any 满天飞	values 无类型提示，拼错键名运行时才报错	官方对 Python 与 JS 后端各有独立入口，配置以官方页为准

表里第二行的排查成本最低，先确认 langgraph dev 是否在运行，再查其他三项。第四行的损失最隐蔽，界面能跑但类型保护全失。

四类坑还可以按暴露时机分两组。第二类在启动阶段立刻暴露，属于显性失败。另外三类都能让界面正常跑起来，问题藏在缺失的功能里，属于隐性失败。显性失败修得快，隐性失败拖得久。

坑	暴露时机	失败性质	首查位置
聊天 SDK 硬接	开发中期想做审批时	隐性	技术选型记录
忘起 Agent Server	启动后第一次请求	显性	终端进程状态
只用 messages	需求方要看业务面板时	隐性	stream 读取代码
类型未配置	写 values 读取代码时	隐性	Type inference 配置

这张表把首查位置固定下来，省掉的是来回翻目录的时间。隐性失败的三行尤其值得在项目初期就过一遍，那时改动成本最低。

失败模式的归类如下图，四类坑分别卡在链路的不同位置。

图里坑二卡在最前端，坑三与坑四卡在同一环节。定位报错时按这张图对位置，比逐个组件翻代码快。

8.2 各能力细节以官方页为准与阅读路线

本文是总览，只给骨架与地图。六大能力、各模式页、Type inference 配置的细节，都在各自官方页里。不确定的地方以官方文档为准，链接统一收在外部引用一章。

给出 51 到 60 篇的板块导览。划分依据是官方两组模式页的结构。

篇目	覆盖范围	对应官方内容
第 51 篇 本篇	板块总览与地图	frontend overview
第 52 到 54 篇	Generative UI 三档	Generative UI 总览与三档模式
第 55 到 60 篇	Patterns 十式精讲	Patterns 组各模式页

十篇的推进逻辑是先立骨架，再按光谱与模式逐层展开。先读总览的好处是后续每篇都能挂到这张地图上，不至于在 20 页里迷路。

两条路线的关系值得说明。第 52 到 54 篇与第 55 到 60 篇没有先后依赖，可以并行推进。Generative UI 三档讲界面怎么生成，Patterns 十式讲交互怎么组织。两路在组合运用处汇合，比如给审批卡片配生成式展示。

阅读节奏上一个建议。每篇展开前先扫一遍对应官方页，再回到本系列对照阅读。官方页给事实与本篇给地图的关系，相当于地图与实地：先看地图定方向，落地时以实地为准。

最后一个提醒回到开篇的定位句。读完这十篇，衡量标准不是记住了多少模式名，而是你的界面是否真的成为控制平面。用户能不能审批、能不能改历史、能不能在断线后接回原线程。这三件事比任何渲染效果都更接近板块的核心承诺。

总结

官方前端 SDK 的定位一句话可以收束：渲染消息的同一个 hook，同时暴露 agent 的持久线程状态、工具调用生命周期、中断、检查点历史与自定义状态值，UI 因此能成为长运行 agent 工作的控制平面。

架构上只有一个主干。createAgent 后端产出暴露流式 API 的已编译图。前端 stream 句柄连接该 API，提供 messages、tool calls、interrupts、values、thread metadata 五件套响应式状态，任何框架渲染。六大能力表、useStream 写法、四框架标签、AGENT_URL 与 langgraph dev，全部长在这条主干上。

实践上的三个抓手。第一，本地先跑 langgraph dev 把 2024 端口立起来。第二，前端用 useStream 一次拿全五件套，别只消费 messages。第三，类型链路按后端语言走对应的 Type inference 入口。剩下的细节，以官方文档为准。

外部引用

• Frontend overview 官方文档：https://docs.langchain.com/oss/python/langchain/frontend/overview
• useStream API 参考：https://reference.langchain.com/javascript/langchain-react/index/useStream
• LangGraph Agent Server：https://docs.langchain.com/oss/python/langgraph/local-server
• Generative UI overview：https://docs.langchain.com/oss/python/langchain/frontend/generative-ui-overview
• langgraphjs 仓库（v1 迁移指南）：https://github.com/langchain-ai/langgraphjs