推理还是行动？解析 ReAct 模式在 NestJS 后端架构中的落地实践

ETA8
6 阅读11分钟

构建企业级流式 AI Agent：基于 NestJS 与 LangChain 的工具调用实战解析

摘要：在过去的一年里，大模型（LLM）的应用从简单的“一问一答”演进到了具备自主能力的“代理模式（Agent）”。开发者们不再满足于模型仅仅会聊天，更希望它能像员工一样，查数据库、搜索网页、甚至发送邮件。但在工程化落地中，如何优雅地处理“长耗时任务”与“实时交互”之间的矛盾？如何利用 NestJS 的架构优势结合 LangChain 的生态实现稳定的工具调用？本文将深度拆解一套基于 ReAct 模式的流式 Agent 实现方案。

一、背景与核心挑战：为什么我们需要 Agent 模式？

传统的 AI 接口调用是静态的：输入一段话，等待几秒，返回一段话。这种方式的上限被锁死在模型的训练数据中。如果用户问："ID 为 001 的员工最近表现如何？”模型若无法访问你的私有数据库，它只能胡编乱造。

Agent 的本质是“推理（Reasoning）”与“行动（Acting）”的闭环。

它不再是一个孤立的黑盒，而是一个能够观察环境（查询工具）、做出决策（调用接口）、并根据结果调整策略的智能体。在企业级应用中，这种模式解决了以下核心痛点：

  1. 数据私有化：模型无需训练私有数据，只需通过工具访问即可。
  2. 操作实时性：可以执行发送通知、更新状态等实时操作。
  3. 逻辑复杂性：能够处理多步骤的任务规划，而非单轮对话。

然而，引入 Agent 模式也带来了显著的工程挑战。最大的矛盾在于 “长耗时任务”与“实时交互” 之间的冲突。工具调用可能涉及网络请求或复杂计算，耗时从几百毫秒到数秒不等。如果等到所有任务结束再返回结果，用户面对的是长达数秒的空白界面，体验极差。因此，流式传输（Streaming） 成为了必选项。

二、核心架构设计：SSE 与响应式流

在 AI 场景下，用户体验的生死线在于“首字响应时间”（Time to First Token）。为了平衡实时性与后端处理逻辑，我们选择了 SSE（Server-Sent Events） 作为通信协议，并配合 RxJS 进行流式数据管理。

1. 为什么选择 SSE 而非 WebSocket？

在 NestJS 中，我们利用 @Sse 装饰器实现服务端推送。虽然 WebSocket 也能实现双向通信，但在 AI 对话场景中，SSE 具有明显的工程优势。

  • 协议兼容性：SSE 基于标准的 HTTP 协议，兼容性更好。企业内部的防火墙、负载均衡器通常对 HTTP 长连接支持良好，而对 WebSocket 可能会有超时或拦截策略。
  • 连接模式：AI 对话通常是“一向单流”模式：客户端发送一次请求，服务端持续推送数据直到结束。SSE 天然契合这种模式，无需像 WebSocket 那样维护复杂的双向心跳和连接状态管理。
  • 资源开销：SSE 的连接建立开销更小，对于高并发的对话场景，服务端压力相对较轻。

工程实现细节：

// NestJS Controller 示例
@Sse('ai/chat')
chat(@Body() dto: ChatDto): Observable<MessageEvent> {
  const stream = this.aiService.generateStream(dto);
  return from(stream).pipe(
    map((chunk) => ({ data: chunk })), // 格式化为标准 SSE 消息
  );
}

在工程考虑上，必须注意以下两点：

  • Content-Type: 必须设置为 text/event-stream，告诉浏览器这不是一次性的 JSON，而是一个持续的流。
  • Transfer-Encoding: 启用 chunked，允许我们将数据分块传输，而不需要预先知道总长度。

2. RxJS：异步事件的“流水线”

在 Controller 层，我们并没有直接使用原生的异步迭代器，而是引入了 rxjs 的 from 和 pipe 操作符。

return from(stream).pipe(
  map((chunk) => ({ data: chunk })),
)

这段代码看似简单，实则蕴含了重要的架构考量。AI 的输出是连续发生的事件，就像一条河流。RxJS 的优势在于它能将这种“连续的异步”抽象成一个 Observable（可观察对象）。

使用 RxJS 的核心价值：

  • 组合性：无论 LLM 返回的是文字片段，还是工具调用的状态标记，我们都可以通过操作符（Operator）进行统一的格式化加工。
  • 错误处理：可以在流中统一捕获异常，转换为友好的错误消息推送给前端，避免连接直接断开。
  • 声明式编程：这种写法比嵌套的回调函数或复杂的 async/await 循环要稳固得多，也更易于测试和维护。

三、Agent Loop 的实现逻辑：如何让 AI“动起来”

在 AiService 中，核心逻辑是一个基于 while(true) 的自主循环。这是 Agent 能够处理多步复杂任务的关键，也是 ReAct（Reasoning + Acting）模式的具体体现。

1. 绑定的艺术：bindTools 与 Zod

我们不能直接把数据库逻辑写在提示词里，那样既不安全也不灵活。LangChain 的 tool 函数配合 zod schema，起到了“契约”的作用。

定义工具时，我们需要提供三个核心要素：

  1. 名称（Name）：模型调用时的标识符。
  2. 描述（Description）：至关重要。模型并不运行你的代码，它只是根据工具的 description 来判断：“我现在的处境是否需要这个工具？”。如果描述模糊，模型可能根本不会调用该工具。
  3. 参数 Schema：通过 zod 定义输入参数（如 userId 必须是字符串），可以有效拦截模型生成的幻觉参数。

2. 状态机的流转：推理与行动

代码中的 while(true) 实际上构建了一个简易的状态机。这个循环并非无限运行，而是通过检测是否还有工具调用来决定退出。

第一阶段：生成流

我们调用 model.stream(messages)。此时 AI 可能返回两种内容：

  • 文本内容：直接 yield 给前端，让用户看到 AI 正在思考或回答。
  • 工具调用指令：含有 tool_calls 字段的 JSON 碎片。

第二阶段：消息聚合（Concatenation）

这是最容易出错的地方。由于是流式返回，工具调用的参数可能是破碎的。

注意：例如，第一个 chunk 可能是 { "id":，第二个是 "001" }。如果我们尝试解析第一个 chunk，必然会报错。

我们必须使用 fullAIMessage.concat(chunk) 将这些碎片聚合成一个完整的对象。这里有一个重要的工程细节：始终在 for await 循环结束后，再去检查 fullAIMessage.tool_calls。 过早地在循环内部尝试解析不完整的工具调用参数，会导致程序频繁崩溃。

第三阶段：工具执行与反馈

当流结束且存在 tool_calls 时，程序暂停与模型的对话，转而去执行本地的 queryUserTool。

关键动作：执行完后，必须将结果封装成 ToolMessage 再次推入 messages 数组。

为什么要喂回去？ 因为 AI 是无状态的。它需要知道它刚才调用的结果是什么。它看到 ToolMessage 后，会在下一次 while 循环中通过这些新信息给出最终总结。如果缺少这一步，AI 就不知道工具执行成功了没有，也无法基于数据回答问题。

四、深度剖析：从工具调用到错误处理

在实际开发过程中，很多开发者会遇到 Zod 报错：expected object, received string。这揭示了 LangChain 内部处理流数据的细节。

  • tool_call_chunks：这是原始的流数据，它的参数通常是未解析的字符串。
  • tool_calls：当你使用 concat 方法聚合了所有碎片后，LangChain 的 AIMessage 类会自动尝试将这些字符串 JSON.parse 成对象。

1. 工具执行异常捕获

如果工具执行失败（例如数据库连接超时），我们不能让程序直接崩溃，也不能让 AI 陷入死循环。建议在工具执行层增加 try-catch，并将错误信息也作为 ToolMessage 反馈给模型。

示例策略：

try {
  const result = await service.query(data);
  return new ToolMessage({ content: JSON.stringify(result), tool_call_id });
} catch (error) {
  // 将错误信息反馈给模型，让它学会自我纠错
  return new ToolMessage({ content: `Error: ${error.message}`, tool_call_id });
}

这样，AI 甚至能学会“自我纠错”，它会根据这个反馈告诉用户：“抱歉，我查询数据库时遇到了网络波动，请稍后再试。”这种透明度极大地提升了用户信任感。

2. 防止无限循环

在极端情况下，模型可能会陷入“调用工具 - 报错 - 再次调用工具”的死循环。为了防止这种情况，我们需要在 while 循环中设置最大迭代次数（例如 5 次）。一旦超过阈值，强制终止循环并返回错误提示。这不仅是保护后端资源，也是防止产生高额的 Token 费用。

3. 上下文管理与安全

每一轮 Agent Loop 都会增加 messages 数组的长度。对于长对话，需要引入窗口记忆（Window Memory） 机制，截断过旧的消息，或者使用摘要技术压缩历史对话。

此外，安全性是一个不可忽视的问题。工具调用赋予了 AI 执行代码的能力。必须确保工具具备权限控制，不能因为 AI 的误判而执行了删除数据等高危操作。建议在工具层增加基于角色的访问控制（RBAC），确保 AI 只能以当前用户的权限执行操作。

五、方案优缺点与工程权衡

任何架构设计都是权衡的结果。基于 NestJS 与 LangChain 的流式 Agent 方案也不例外。

优点分析

特性说明
极致的体验在 AI 思考或说话时，前端立刻有反应；在 AI 查数据库时，后端静默执行，逻辑清晰。
解耦性强NestJS 的依赖注入（DI）让我们能轻松更换底层的 CHAT_MODEL。无论是 OpenAI 还是国产大模型，只要符合 LangChain 规范，业务代码几乎不用动。
可扩展性如果明天需要增加一个“发邮件”的功能，只需要定义一个新的 tool 并放入 bindTools 数组即可，不需要修改复杂的 while 循环逻辑。

缺点与改进方向

  1. 上下文膨胀：随着对话进行，Token 消耗会指数级增长。需要引入更高级的记忆管理策略。
  2. 串行阻塞：目前的逻辑是 for (const toolCall of toolCalls)，如果 AI 一次性要调三个接口，它们是排队执行的。在高性能要求的场景下，应改用 Promise.all 并行处理，但这也带来了事务一致性的挑战。
  3. 调试难度：流式异步逻辑比同步代码更难调试。建议引入链路追踪（如 OpenTelemetry），记录每一次工具调用的耗时、Token 消耗和模型决策路径。

六、落地建议与最佳实践清单

为了确保方案在生产环境的稳定性，建议遵循以下最佳实践：

  • [ ] 设置超时限制：为每个工具调用设置明确的超时时间，防止单个工具卡死整个 Agent 循环。
  • [ ] 敏感信息脱敏：在将工具结果返回给模型之前，检查是否包含敏感信息（如密码、密钥），必要时进行脱敏处理。
  • [ ] 人机协作（Human-in-the-loop）：对于高危操作（如删除数据、转账），可以在工具执行前插入人工确认环节，让 AI 生成计划，人来批准执行。
  • [ ] 成本监控：建立 Token 消耗监控看板，设定每日预算上限，防止异常调用导致成本失控。
  • [ ] 降级策略：当 LLM 服务不可用时，应有降级方案（如返回预设提示或切换到备用模型），保证服务可用性。

七、结语

构建一个智能代理，不仅仅是写一段 Prompt（提示词），更是一场关于异步流、状态管理和工程健壮性的挑战。通过 NestJS 的严谨架构与 LangChain 的灵活生态，我们可以把 LLM 从一个“聊天软件”改造成一个真正的“业务中台”。

写代码就像是挖渠引水，RxJS 铺设了河道，Agent Loop 则是水闸。只有渠修得足够稳，AI 的智慧之水才能精准地流向业务最需要的地方。

技术最终是为人服务的。在追求架构优雅的同时，不要忘记关注最终用户的感受。一个稳定、透明、可预期的 AI 助手，远比一个聪明但不可控的黑盒更有价值。希望这套基于 NestJS 的流式 Agent 方案，能为你在企业级 AI 落地的道路上提供一份坚实的参考。

avatar
文章
阅读
粉丝