AI Agent / 系统课时
设计异步与流式通信
设计异步与流式通信
本节解决智能体执行过程中任务耗时长、事件无法实时反馈的问题。通过 asyncio、FastAPI 和流式传输机制设计通信链路,让模型生成、工具调用和客户端状态更新能够并行处理并持续返回结果。
学习目标
- 理解智能体系统为什么需要异步执行模型和工具任务
- 掌握 asyncio 在 Agent Runtime 中的基本组织方式
- 了解 SSE 与 WebSocket 在实时通信中的职责区别
异步通信解决的问题
智能体任务通常不是一次请求一次响应。一次执行可能包含模型推理、多个工具调用、外部接口访问和状态更新。如果使用同步流程,客户端只能等待全部完成后才能看到结果。
异步设计可以让 Runtime 在等待某个任务时继续处理其他事件,同时通过流式通信不断向客户端发送进度。
典型链路包括:客户端提交任务、Runtime 创建异步任务、模型产生增量结果、工具返回事件、客户端实时更新状态。

使用 asyncio 管理 Agent 任务
Python 的 asyncio 适合处理大量等待型任务,例如网络请求、模型调用和工具执行。智能体 Runtime 可以使用协程拆分不同阶段。
import asyncio
async def call_model():
# 模拟模型生成过程
await asyncio.sleep(1)
return "模型结果"
async def call_tool():
# 模拟工具执行过程
await asyncio.sleep(1)
return "工具结果"
async def run_agent():
model_task = asyncio.create_task(call_model())
tool_task = asyncio.create_task(call_tool())
results = await asyncio.gather(model_task, tool_task)
return results
result = asyncio.run(run_agent())
print(result)预期输出
['模型结果', '工具结果']create_task 会立即调度协程执行,gather 等待多个任务完成。实际项目中还需要增加超时、取消和异常隔离机制。
SSE 与 WebSocket 的职责划分
流式通信方式需要根据交互方向选择。
| 方式 | 特点 | 适合场景 |
|---|---|---|
| SSE | 服务端持续推送文本事件 | 模型 token 流、任务进度通知 |
| WebSocket | 双向长连接通信 | 实时控制、多人协作、复杂交互 |
对于大多数 Agent 对话场景,SSE 已经能够满足服务端持续输出需求。客户端发送请求后,通过事件流接收模型增量内容和工具状态。
当客户端需要主动发送控制指令,例如暂停任务、修改参数或多人协同操作时,WebSocket 更合适。
在 FastAPI 中组织流式接口
FastAPI 可以通过生成器持续返回事件流。下面是简化的 SSE 示例。
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import asyncio
app = FastAPI()
async def event_stream():
for message in ["开始", "处理中", "完成"]:
yield f"data: {message}\n\n"
await asyncio.sleep(1)
@app.get("/events")
async def events():
return StreamingResponse(
event_stream(),
media_type="text/event-stream"
)预期结果
客户端持续收到事件:
data: 开始
data: 处理中
data: 完成实际 Agent 系统中,事件内容通常会使用前面定义的 Pydantic 事件模型序列化后发送。
异步设计中的边界问题
异步并不代表所有任务都应该并行。工具之间存在依赖时必须保持顺序,否则可能读取到未更新的数据。
还需要处理以下情况:
- 用户取消任务时,需要传播取消信号
- 工具超时时,需要释放资源并返回失败事件
- 多个客户端订阅同一任务时,需要管理事件广播
良好的流式架构应该让执行状态、事件传输和业务逻辑保持分离。
本课总结
- asyncio 为智能体执行提供并发任务组织能力。
- SSE 适合模型输出和状态推送,WebSocket 适合双向实时控制。
- 流式系统需要同时考虑取消、超时、错误和事件管理。
下一课预告
下一课将继续完善智能体工程架构,介绍运行时组件如何组合并形成可扩展的 Agent 系统。