AI Agent / 系统课时

设计异步与流式通信

设计异步与流式通信

本节解决智能体执行过程中任务耗时长、事件无法实时反馈的问题。通过 asyncio、FastAPI 和流式传输机制设计通信链路,让模型生成、工具调用和客户端状态更新能够并行处理并持续返回结果。

学习目标

  • 理解智能体系统为什么需要异步执行模型和工具任务
  • 掌握 asyncio 在 Agent Runtime 中的基本组织方式
  • 了解 SSE 与 WebSocket 在实时通信中的职责区别

异步通信解决的问题

智能体任务通常不是一次请求一次响应。一次执行可能包含模型推理、多个工具调用、外部接口访问和状态更新。如果使用同步流程,客户端只能等待全部完成后才能看到结果。

异步设计可以让 Runtime 在等待某个任务时继续处理其他事件,同时通过流式通信不断向客户端发送进度。

典型链路包括:客户端提交任务、Runtime 创建异步任务、模型产生增量结果、工具返回事件、客户端实时更新状态。

智能体异步与流式通信链路图

使用 asyncio 管理 Agent 任务

Python 的 asyncio 适合处理大量等待型任务,例如网络请求、模型调用和工具执行。智能体 Runtime 可以使用协程拆分不同阶段。

python
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)

预期输出

text
['模型结果', '工具结果']

create_task 会立即调度协程执行,gather 等待多个任务完成。实际项目中还需要增加超时、取消和异常隔离机制。

SSE 与 WebSocket 的职责划分

流式通信方式需要根据交互方向选择。

方式 特点 适合场景
SSE 服务端持续推送文本事件 模型 token 流、任务进度通知
WebSocket 双向长连接通信 实时控制、多人协作、复杂交互

对于大多数 Agent 对话场景,SSE 已经能够满足服务端持续输出需求。客户端发送请求后,通过事件流接收模型增量内容和工具状态。

当客户端需要主动发送控制指令,例如暂停任务、修改参数或多人协同操作时,WebSocket 更合适。

在 FastAPI 中组织流式接口

FastAPI 可以通过生成器持续返回事件流。下面是简化的 SSE 示例。

python
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"
    )

预期结果

text
客户端持续收到事件:
data: 开始

data: 处理中

data: 完成

实际 Agent 系统中,事件内容通常会使用前面定义的 Pydantic 事件模型序列化后发送。

异步设计中的边界问题

异步并不代表所有任务都应该并行。工具之间存在依赖时必须保持顺序,否则可能读取到未更新的数据。

还需要处理以下情况:

  • 用户取消任务时,需要传播取消信号
  • 工具超时时,需要释放资源并返回失败事件
  • 多个客户端订阅同一任务时,需要管理事件广播

良好的流式架构应该让执行状态、事件传输和业务逻辑保持分离。

本课总结

  • asyncio 为智能体执行提供并发任务组织能力。
  • SSE 适合模型输出和状态推送,WebSocket 适合双向实时控制。
  • 流式系统需要同时考虑取消、超时、错误和事件管理。

下一课预告

下一课将继续完善智能体工程架构,介绍运行时组件如何组合并形成可扩展的 Agent 系统。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计异步与流式通信

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通