[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 相关: Event Type, Run Event

Progress Event

一句话定义

Progress Event 是 Agent 执行过程中发出的进度更新事件。它让用户知道”正在执行第 2 步，共 5 步”，而不是只看到一个 loading 动画。

核心原理

数据格式

{
  "event": "progress",
  "data": {
    "message": "正在搜索知识库...",
    "step": 2,
    "total_steps": 5,
    "percent": 40
  }
}

前端渲染

function ProgressBar({ progress }: { progress: ProgressData }) {
  return (
    <div className="progress-bar">
      <div className="progress-text">{progress.message}</div>
      <div className="progress-track">
        <div
          className="progress-fill"
          style={{ width: `${progress.percent}%` }}
        />
      </div>
      <div className="progress-step">
        步骤 {progress.step}/{progress.total_steps}
      </div>
    </div>
  );
}

常见坑

1. 不做进度更新: 用户只看到 loading
2. 进度不准确: 显示 80% 但实际才 30%
3. 更新太频繁: 每秒更新 10 次，UI 闪烁

参考资料

• Event Type
• Run Event