LangChain 前端流式输出实现指南

建议将代理部署至 LangSmith 以获取生产级托管与观测能力。

useStream 参数详解

useStream 返回值

线程管理

通过 threadId 和 onThreadId 回调管理对话线程，便于持久化和恢复。

const [threadId, setThreadId] = useState<string | null>(null);
const stream = useStream({
  // ...
  threadId,
  onThreadId: setThreadId,
});

推荐将 threadId 存储到 URL 参数或 localStorage。

页面刷新后恢复

设置 reconnectOnMount: true 可自动恢复运行流：

const stream = useStream({
  // ...
  reconnectOnMount: true,
  // 默认使用 sessionStorage
});

支持自定义存储，或手动通过 onCreated 和 joinStream 控制恢复。

乐观更新（Optimistic Updates）

在网络请求前乐观更新客户端状态，提供即时反馈。

stream.submit(
  { messages: [newMessage] },
  {
    optimisticValues: (prev) => ({
      ...prev,
      messages: [...(prev.messages ?? []), newMessage]
    })
  }
);

乐观线程创建

预先生成线程 ID，实现即时导航。

const optimisticThreadId = crypto.randomUUID();
stream.submit(
  { messages: [...] },
  { threadId: optimisticThreadId }
);

缓存线程显示

使用 initialValues 立即显示缓存数据。

分支（Branching）

通过编辑历史消息或重新生成 AI 响应创建分支。使用 getMessagesMetadata() 获取检查点信息。

类型安全流式（Type-safe Streaming）

支持与 createAgent、StateGraph 和 Annotation 类型结合，实现类型推断。

高级特性

• 渲染工具调用：显示工具调用状态。
• 自定义流式事件：通过 writer 发送自定义数据。
• 事件处理：多种回调处理更新、元数据等。
• 多代理流式：支持多代理协作。
• 人与循环（Human-in-the-Loop）：处理中断和用户输入。
• 自定义状态类型与传输：灵活扩展。

总结

useStream Hook 极大简化了 LangGraph 在前端的流式集成，提供完整的消息管理、线程持久化、分支持和乐观更新等功能。开发者可结合 LangSmith 部署快速构建生产级生成式聊天界面。建议参考官方示例（如 session-persistence）进行实践。

参考资料：https://docs.langchain.com/oss/python/langchain/streaming/frontend