真正工程里,一个常见错误是:
RunStep 一套
Streaming Message 另一套
最后两者不一致。
比如 Run 实际做到:
Step 7
前端却只收到:
Step 5
更好的方式是,Agent 每产生一个有意义的 RunStep,就顺便转成一个 Streaming Event。
定义 ProgressEvent
from dataclasses import dataclass
from datetime import datetime, timezone
def utc_now() -> str:
return datetime.now(
timezone.utc
).isoformat()
@dataclass
class ProgressEvent:
run_id: str
step: int
event_type: str
message: str
status: str
created_at: str
然后每个 RunStep:
reason
tool
observation
映射成更适合用户看的消息。
比如内部 Step:
tool=read_file
arguments={"path":"app.py"}
前端事件不一定需要完整参数。
可以变成:
正在读取 app.py...
内部 Observation:
ModuleNotFoundError: requests
前端可以:
发现依赖错误:requests 未安装
而完整 traceback 留 Trace。
一个简单 EventBus
为了把 AgentEngine 产生的事件送给 SSE,我们可以先实现一个非常简单的队列。
import queue
from dataclasses import dataclass
@dataclass
class ProgressEvent:
event_type: str
message: str
class EventBus:
def __init__(self):
self._queue = queue.Queue()
def publish(
self,
event: ProgressEvent,
) -> None:
self._queue.put(
event
)
def get(
self,
timeout: float = 1.0,
) -> ProgressEvent:
return self._queue.get(
timeout=timeout
)
后面 Agent:
event_bus.publish(...)
SSE:
event_bus.get(...)
这就形成:
AgentEngine
↓
EventBus
↓
SSE
↓
Frontend
为什么 EventBus 是很好的边界?
因为 AgentEngine 不应该知道:
Flask Response
SSE 格式
浏览器 EventSource
它只应该:
emit event
怎么把事件送给客户端,是 Server 层的事情。
这和前面所有设计原则一致,把网络协议和 Agent Runtime 解耦。
从工程结构看,最稳的做法就是让 RunStep 先转成产品层 ProgressEvent,再通过 EventBus 交给 SSE。这样 Runtime 只负责“发生了什么”,Server 层才负责“怎么发给客户端”。
![图片[1]-小节三:把 RunStep 变成 Streaming Event——不要再单独维护一套“假进度”-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1626.png)
这个边界很值得保留。以后 SSE 换成 WebSocket、消息队列,甚至同时有多个消费者,AgentEngine 本身都不需要跟着改。
© 版权声明
文章版权归作者所有,未经允许请勿转载。
THE END

















请登录后查看评论内容