Agent 状态与事件速查

Agent 工程最容易出现的错觉是：界面还在转，就以为系统“正在思考”。真正可调试的系统必须回答：

1. 当前处于哪个阶段？
2. 已经消耗了什么输入？
3. 产生了哪些状态变化？
4. 正在等待模型、工具、用户还是其他 Agent？
5. 失败后能否安全重试，是否会重复副作用？

通用状态信封

不同功能可以共用一组最小字段：

字段	用途
run_id	一次端到端运行的稳定标识
trace_id	串起 API、模型、工具、数据库和子代理
sequence	事件顺序；支持 SSE 重连去重
phase	当前阶段，如 model_waiting、tool_running
status	queued/running/waiting/succeeded/failed/cancelled
parent_run_id	子代理或子任务的父运行
attempt	当前重试次数
started_at/updated_at	判断停滞、超时和耗时
input_ref/output_ref	指向脱敏输入和产物，不把大对象塞进事件
error_code	稳定的机器可读失败类型
policy_decision	工具、网络、文件、密钥权限的判断结果

事件建议采用过去式：model.requested、tool.completed，表示“事实已经发生”，而不是模糊的 processing。

1. Agent Loop

关键状态：messages、iteration、max_iterations、pending_tool_calls、usage。
关键不变量：每个工具结果必须和原工具调用关联；达到最大轮数必须终止；工具执行前必须经过策略检查。

2. Planning

关键状态：plan_version、步骤 id/status/depends_on/evidence、current_step。
不要只保存自然语言 Todo；步骤需要稳定 ID、依赖和完成证据，否则无法恢复或并发更新。

3. Subagent

父 Agent 应保存 child_run_id、任务边界、允许工具、上下文摘要、预算和返回契约。

parent.delegation_requested
→ child.started
→ child.progressed*
→ child.completed | child.failed | child.cancelled
→ parent.child_result_received

父任务取消时必须级联取消仍在运行的子任务。子代理只接收完成任务所需的最小上下文，不继承所有私密记忆。

4. Agent Team

团队状态分三层：

• 私有状态：每个角色自己的消息与草稿；
• 协作状态：任务板、消息、共享产物引用；
• 管理状态：成员、角色、预算、终止条件。

观察重点是消息归属、任务认领、版本冲突和级联终止，而不是把所有人的完整对话拼成一个超长上下文。

5. MCP

transport.connected
→ session.initialized
→ capabilities.discovered
→ tool.requested
→ authorization.checked
→ tool.completed | tool.failed
→ session.closed

关键状态：传输类型、会话 ID、协议版本、能力列表、请求 ID、权限范围、超时。远程 MCP 还必须观察鉴权失败、限流和断线恢复。

6. Hook

Hook 是某个生命周期节点上的确定性检查或副作用：

关键状态：hook_name、event_type、decision、reason、duration。Hook 本身失败时要明确采用 fail-open 还是 fail-closed。

7. Goal

Goal 比计划寿命更长。它保存目标、成功标准、当前证据、预算和阻塞条件；计划只是达成目标的一次执行方案。

active → progressing → achieved
  └────→ blocked → active
  └────→ abandoned

每次更新都应带证据和版本号，防止旧任务覆盖新状态。不得因为“预算快用完”就把未完成目标标记为完成。

8. RAG

关键状态：查询改写、候选文档及分数、最终上下文、引用映射、拒答原因、工单 ID。用户记忆不能覆盖企业政策知识。

9. Skill 发布

关键状态：slug/version/checksum/status/evaluation/approval/capabilities。已发布包不可覆盖；回滚是切换默认版本，不是改写历史包。

10. GitLab MR Review

MR event
→ pipeline.created
→ deterministic_checks.completed
→ reviewer.completed
→ verifier.completed
→ report.published
→ gate.allowed | gate.blocked

关键状态：项目、MR IID、源/目标 SHA、diff fingerprint、检查结果、问题级别、证据位置、报告版本。新提交必须生成新 fingerprint；P0/P1 或确定性检查失败才阻断，P2/P3 留给人工判断。

SSE 重连与幂等

浏览器断线后携带最后收到的事件序号重新订阅。服务端只重放事件，不重新执行 Skill：

POST /runs       → 创建一次运行并返回 run_id
GET /events      → 订阅/重放 run_id 的事件
Last-Event-ID    → 从下一条 sequence 继续
Idempotency-Key  → 防止重复 POST 产生第二次副作用

只要把“运行创建”和“事件订阅”拆开，刷新页面就不会重复创建工单、发表评论或执行工具。