AI Agent / 系统课时
建立运行事件流
建立运行事件流
本课解决智能体执行过程不可观察的问题,通过事件模型记录请求、工具调用、观察结果、错误和完成状态,让运行过程能够被 UI 展示、日志系统记录并用于问题定位。
学习目标
- 理解 Agent Runtime 中事件流的作用和基本组成。
- 设计统一的事件结构,记录执行过程中的关键变化。
- 实现简单的事件发布与消费机制。
为什么需要运行事件流
智能体执行任务时通常包含多个阶段:接收请求、调用模型、执行工具、获取观察结果、继续推理,直到任务完成。如果只保存最终回答,中间过程会全部丢失,开发者无法判断任务为什么成功或失败。
事件流把一次任务拆成连续发生的事件。每个事件描述一个状态变化,例如模型开始生成、工具被调用、工具返回结果、执行出现异常。这样运行时就拥有了一条可追踪的时间线。
事件模型的核心设计
一个基础事件通常需要包含事件身份、类型、时间和关联关系。id 用于唯一定位事件,parentId 用于表示事件来源,timestamp 用于排序,type 用于区分不同阶段。
常见事件类型包括:
- request:用户任务进入运行时。
- tool_call:智能体请求执行工具。
- observation:工具或环境返回观察结果。
- error:执行过程中出现错误。
- done:任务最终结束。
事件结构示例:
ts
interface AgentEvent {
id: string;
parentId?: string;
type: "request" | "tool_call" | "observation" | "error" | "done";
timestamp: number;
payload: unknown;
}
const event: AgentEvent = {
id: "evt-<ID>",
type: "tool_call",
timestamp: Date.now(),
payload: {
tool: "readFile",
path: "<PATH>"
}
};预期输出
text
生成一个表示工具调用阶段的 AgentEvent 对象。实现事件发布链路
运行时通常不会直接把事件写入界面,而是通过事件总线解耦执行逻辑和展示逻辑。执行模块负责产生事件,订阅方可以负责日志、界面更新或调试分析。
ts
type EventHandler = (event: AgentEvent) => void;
class EventBus {
private handlers: EventHandler[] = [];
subscribe(handler: EventHandler) {
this.handlers.push(handler);
}
publish(event: AgentEvent) {
for (const handler of this.handlers) {
handler(event);
}
}
}
const bus = new EventBus();
bus.subscribe(event => console.log(event.type));
bus.publish({
id: "evt-<ID>",
type: "done",
timestamp: Date.now(),
payload: { status: "success" }
});预期输出
text
done事件流在调试中的价值
当任务失败时,事件链可以帮助开发者定位问题发生的位置。例如发现工具调用成功但后续推理失败,可以重点检查上下文组装;如果工具返回错误,则检查参数校验和执行环境。
事件流还为后续能力提供基础,例如实时展示 Agent 思考进度、记录运行轨迹、统计工具调用耗时,以及构建任务回放功能。
运行事件流的关键不是记录所有文本,而是记录影响任务状态变化的重要节点。合理的事件粒度能够在可观测性和存储成本之间取得平衡。
按自己的节奏,确认真正理解。