LangGraph + FastAPI + SSE：构建流式AI Agent的实战指南

构建一个 AI Agent 并不难，真正考验架构能力的是：如何通过 HTTP API 暴露它、集成真实工具，并把执行过程实时推送给客户端。本文基于一个可运行的开源示例，拆解 LangGraph、FastAPI 与 Server-Sent Events 三者的协作方式，并厘清从演示到生产之间的关键缺口。

为什么要把 Agent 编排和 API 传输分开？

LangGraph 负责 Agent 的执行流程：节点调度、LLM 推理、工具调用。FastAPI 则负责把这些能力暴露成清晰的 HTTP 接口。两者职责截然不同，混在一起会让代码难测试、难演进。

一个有用的心智模型是：客户端不需要理解 Agent 如何选择工具、如何管理内部状态，它只需要和一个边界明确的 HTTP 接口交互。这种分离带来的好处是双向的——Agent 可以脱离 HTTP 层独立测试，API 层也可以在后续引入新客户端时保持不变。说白了，这就是把"编排"和"传输"当成两个可独立变化的系统来设计。

LangGraph 是 LangChain 团队推出的 Agent 编排框架，核心抽象是「图」：节点代表一个计算步骤（如调用 LLM、执行工具），边代表步骤之间的流转条件。相比链式调用，图结构天然支持循环、分支和条件跳转，因此适合需要多轮推理与工具调用的 Agent。它内置了状态管理机制，每个节点读写共享的 State，框架负责在节点间传递和合并状态。这使得「谁执行、执行到哪一步」都由图来掌控，而 HTTP 层只需关心如何触发这张图和如何把结果送回去——这正是文中强调职责分离的技术前提。

给 Agent 一个真实工具：天气查询

一个只能生成文本的 Agent 没什么意思。示例中接入了一个基于 Open-Meteo 的天气工具，引入了完整的执行链路：

1. 用户提出天气相关问题；
2. 模型判断是否需要调用工具；
3. 工具向外部发起请求获取天气数据；
4. 结果返回给 Agent；
5. Agent 基于结果生成回答。

这条链路看似简单，却引入了纯 LLM 补全不存在的问题：网络失败、工具报错、延迟、重试。一旦你的 Agent 需要对接数据库或业务系统，这些工程约束会以同样的方式浮现。换句话说，天气工具只是一个"最小可用"的外部依赖样本。

两种响应模式：普通 JSON 与流式 SSE

FastAPI 示例同时展示了两种响应方式。普通 JSON 模式适合简单集成——客户端发请求，等到最终结果即可。而在 Agent 执行涉及多个步骤时，用户可能要等待数秒甚至更久，这时流式响应就派上用场了。

流式模式基于 Server-Sent Events，它通过 HTTP 响应持续推送事件。一条简化的 SSE 消息长这样：

event: message
data: {"content":"Processing your request..."}

需要说明的是，这里只是演示 SSE 格式，并非仓库中的精确事件契约。对于 AI 应用来说，流式输出的价值在于让长耗时操作变得可见，从而改善交互体验。

Server-Sent Events（SSE）是 HTML5 规范定义的一种单向推送协议，客户端通过普通 HTTP 请求建立连接，服务端以 text/event-stream 的 MIME 类型持续写入文本流。每条消息由若干字段组成，常用的是 event（事件类型）、data（负载）和 id（事件 ID），消息之间以空行分隔。相比 WebSocket，SSE 基于纯 HTTP、无需协议升级，天然适合「服务端单向推送进度或增量结果」的场景，如 AI 流式输出。它的局限是只能服务端到客户端单向通信、默认受浏览器连接数限制，且断线重连依赖客户端实现（可通过 Last-Event-ID 做续传）。

流式带来的是体验升级，也是工程难题

SSE 让客户端能边收到事件边处理，但一旦从"能跑通"走向"可靠服务"，一串问题就会冒出来：

• 客户端断开连接后，服务端如何处理？
• 流已经开始后，错误如何传达给客户端？
• 客户端如何识别流已结束？
• 工具在执行中途失败怎么办？

这些问题在演示阶段可以回避，但在生产环境会直接决定系统的可用性。示例仓库刻意保持精简，正是为了让你在看清每个组件职责后，再自行补齐这些边界情况。

核心设计原则：Agent 拥有执行权，API 只负责传输

示例强调的一条原则是：不要把 Agent 编排逻辑和 HTTP 传输逻辑搅在一起。

Agent 应该自己掌控执行流和工具交互，FastAPI 层只处理请求、响应和流式传输。这样做的好处不止于测试——它为后续引入认证、持久化、可观测性等功能预留了清晰的边界。当你要替换或升级某个组件时，改动范围是可预期的。

这个示例还没有解决什么？

能跑的 Agent API 不等于生产可用。在用于关键业务前，至少还有几类问题需要正视。

持久化与检查点：长时间运行或多步骤的 Agent，可能需要在中断后恢复执行状态。LangGraph 的 checkpoint 能力可以在这里发挥作用。

重试与幂等性：当工具会修改外部系统时，重试可能造成严重后果。比如支付操作，绝不能因为重试而重复扣款。原文的提醒很关键——checkpoint 本身并不能保证幂等性，外部副作用需要单独的保护机制。

可观测性：生产系统需要追踪 Agent 执行、LLM 调用、工具输入输出、错误和延迟。LangSmith 是 LangGraph 生态中一个可选的追踪方案，可以覆盖执行、节点和工具调用级别。

安全与运维管控：认证、限流、密钥管理、结构化日志、部署配置，都需要根据具体环境落实。

这些不是"不要动手做示例"的理由，而是"不要把可运行的基础误当成完整生产系统"的理由。

幂等性（Idempotency）指同一操作执行一次与执行多次对系统产生的影响相同。在 Agent 场景中，工具调用往往带有外部副作用——下单、扣款、发消息——若因超时或断连而重试，就可能造成重复操作。常见做法是为每次请求生成唯一的幂等键（Idempotency Key），服务端记录已处理的键并在重复请求时直接返回先前结果，或借助数据库唯一约束、去重表来兜底。需要特别注意的是，LangGraph 的 checkpoint 保存的是执行状态，它保证「从哪里继续」，但并不能阻止工具被再次调用，因此外部副作用必须由独立的幂等机制来守护。

动手试试：跑起来，然后替换工具

开源仓库 salada-dados/langgraph-fastapi-example 包含了实现代码和搭建说明。建议从 README 开始，在本地跑通示例，观察 Agent、工具集成、FastAPI 端点和 SSE 流式输出是如何拼在一起的。

最有价值的下一步练习，是把天气工具替换成你自己业务相关的 API。在替换的过程中，你会自然地触碰到那些最终必须解决的运维问题——这正是示例的设计意图。

小结

这个示例用最小的代码量建立了一个可工作的基础：LangGraph 管编排，FastAPI 管接口，SSE 管推送，Open-Meteo 作为真实外部工具。它的价值不在于功能全，而在于把每个组件的职责划清楚。从演示到生产之间的差距是真实存在的，但只有先搭起这个基础，你才能看清差距在哪里。