用 FastAPI 将智能体封装成流式服务
教程将 Python 智能体推理循环封装为异步 FastAPI 服务,通过 SSE 推送工具启动、文本增量和完成事件。实现复用 Pydantic 输入模式,并结合 StreamingResponse 与防缓冲响应头输出事件流。
AI 深度解读
一个能在本地运行的 Python Agent,要变成网页能调用的服务,还得解决请求校验、等待外部接口和过程输出。作者的方案是用异步 FastAPI 包住推理循环,再通过 SSE 持续发送工具执行和文本生成事件。
路线很清楚:FastAPI 接请求,Pydantic 校验输入,StreamingResponse 返回事件流。不过,这份原文只是教程摘要,没有完整代码、性能实测或部署验证。它适合帮助我们理解改造方向,还不足以直接充当上线指南。
为什么用 FastAPI 包住 Agent
作者在 Post #27 构建了独立运行的 Python Agent,Post #28 则把推理循环放进异步 FastAPI 微服务。Agent 的推理职责没有变,变化在于它开始通过 HTTP 接收任务,并把执行过程返回给调用方。
作者选择 FastAPI,首先看中的是原生 ASGI 和 async/await。调用 GitHub REST API、查询向量数据库时,程序往往需要等待外部响应。异步处理希望让服务在这段等待时间里继续处理其他任务。
异步能否减少阻塞,取决于推理循环内部是否也使用可异步等待的调用。
原文没有展示这些依赖的实现,因此不能仅凭路由用了 async/await,就认定整条执行链已经不会阻塞。这里讨论的也是 I/O 等待,不是让推理计算自动变快。
另一个理由是 Pydantic。作者提出,Agent 工具输入的 schema 可以兼作 FastAPI 请求体的校验模型,减少重复维护字段和类型的工作。
这个做法有适用边界:工具参数与 HTTP 请求结构需要足够接近。如果请求还包含会话信息等额外字段,就需要进一步设计请求模型。原文没有展开这一层。
SSE 要传递的,不只是最终答案
作者用 SSE(Server-Sent Events,服务器发送事件)把 Agent 的运行过程拆成事件流,列出三种自定义事件:
event: tool-start表示开始调用工具。event: text-delta表示发送增量文本。event: done表示任务结束。
对于前端,这种划分比只等待最终响应更有用:界面可以分别表达工具执行、文本逐步出现和任务完成,不必把整个过程都压成一个加载状态。
服务端的实现方向是定义异步生成器 async def agent_event_stream(),逐步 yield SSE 帧,再交给 FastAPI 的 StreamingResponse,设置 media_type='text/event-stream',并添加防缓冲响应头。
这里有两个层次:生成器负责逐步产出事件,StreamingResponse 负责把它们作为响应流发送。作者称事件帧符合 W3C 规范,但摘要没有给出帧的完整格式,也没有列出防缓冲响应头的具体名称和值。
原文给出了流式接口的骨架,没有给出可直接核验的完整实现。
我的判断
这个方向是合理的。把独立 Agent 包成服务,再用明确的事件类型暴露运行过程,能让前端更容易组织交互;复用 Pydantic 模型,也有机会减少接口与工具之间的定义重复。
但作者没有提供并发量、响应延迟、资源占用或对照实验,因此不能据此判断 FastAPI 比其他框架更快,或者 SSE 一定优于其他通信方式。这些选择目前属于设计取舍。
如果产品只需要一次性展示最终结果,普通 JSON 响应也能满足需求;需要持续展示执行进度时,SSE 才更贴近这篇方案。错误事件、客户端断开后的任务处理,以及部署链路是否缓冲,原文都没说清,需要在实际接入时补齐。
能拿来做什么
- 已有独立 Python Agent 时,可以先梳理推理循环中的 GitHub REST API 和向量数据库调用,确认哪些等待能够使用异步客户端,再接入 FastAPI。
- 前端可以围绕
tool-start、text-delta、done定义事件处理逻辑,分别驱动工具状态、文本追加和完成状态。 - 复用 Pydantic schema 前,先核对工具参数与 HTTP 请求体是否一致;出现额外字段时,单独定义请求模型。
- 接入 StreamingResponse 后,在实际部署链路验证事件是否逐条到达,并补充错误与断开连接时的处理,避免仅凭本地输出判断流式接口已经完成。