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 思考进度、记录运行轨迹、统计工具调用耗时,以及构建任务回放功能。

运行事件流的关键不是记录所有文本,而是记录影响任务状态变化的重要节点。合理的事件粒度能够在可观测性和存储成本之间取得平衡。

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

目录与阅读设置

阅读设置

17

记录一个想法

建立运行事件流

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

登录哪都通