[!info] related notes

• 上层入口：Agent Engineering MOC、AI Agent Application MOC
• 核心概念：Agent Runtime
• 工具执行：Tool Calling Engineering MOC
• 质量与观测：Agent Evals MOC、Observability Engineering MOC

Agent Runtime MOC

知识总览

filters:
  and:
    - 'file.ext == "md"'
    - 'file.inFolder("z")'
    - 'this.file.links.contains(file)'
    - 'file.path != this.file.path'
formulas:
  knowledge: 'file.asLink(title)'
properties:
  formula.knowledge:
    displayName: 知识
  note.description:
    displayName: Description
  note.mastery:
    displayName: Mastery
views:
  - type: table
    name: 知识总览
    order:
      - formula.knowledge
      - note.description
      - note.mastery
    columnSize:
      formula.knowledge: 280
      note.description: 760
      note.mastery: 56

[!abstract] 核心认识 Agent Runtime 是把模型决策变成有生命周期、有状态、有权限、有恢复能力的执行系统。它不是简单的模型循环，而是负责 Run 调度、事件、Checkpoint、Interrupt/Resume、取消、重试、并发和审计的控制面。

一张图看执行链

Thread
  └─ Run
      ├─ Step: model decision
      ├─ Step: tool execution
      ├─ State update
      ├─ Event / Trace append
      ├─ Checkpoint
      └─ Completed / Failed / Interrupted / Cancelled

推荐阅读顺序

1. Agent Runtime：职责边界。
2. Run、Step、Run State：执行单位与状态机。
3. Run Event、Trace：发生过什么、如何观测。
4. Checkpoint：保存可恢复状态。
5. Interrupt / Resume 生命周期：真正暂停并等待外部输入。
6. Historical / Counterfactual Replay：复现和比较历史执行。
7. Timeout、Cancellation、Retry Policy：失败控制。
8. Concurrency Control、Backpressure：容量与调度。
9. Tool Idempotency、接口幂等设计：副作用安全。
10. Sandbox、Permission Boundary：隔离与权限。
11. Configuration / Execution Provenance：恢复和审计依据。

四个容易混淆的状态层

状态层	回答的问题	常见存储
Business State	业务事实是什么	业务数据库
Run State	这次任务执行到哪里	Runtime Store
Checkpoint	从哪里可以安全恢复	Checkpoint Store
Trace / Event	过程中发生过什么	Event / Trace Store

[!warning] 关键边界 Checkpoint 不能替代业务数据库；Trace 也不能直接当恢复状态。恢复需要受版本、幂等和副作用边界约束。

Interrupt / Resume 的真实闭环

Runtime reaches approval point
→ persist state + checkpoint
→ Run = interrupted
→ emit approval-required event
→ backend/client collects decision
→ validate actor + payload + current version
→ resume from checkpoint

只在前端弹一个确认框、而后端继续运行，不是 Human-in-the-loop。

Timeout、Cancellation 与 Retry

Deadline expires
→ request cancellation
→ release resources / stop child work
→ classify failure
→ retry only if safe and within budget

Timeout 只是判定“等太久”；Cancellation 才负责停止工作；Retry 又必须结合错误类型、幂等和总预算。

一个成熟 Runtime 的控制面

• Run state machine 与 CAS / lease；
• scheduler / queue / concurrency quota；
• checkpoint schema 与版本迁移；
• interrupt token 与 actor authorization；
• tool permission、sandbox、timeout 与 idempotency；
• retry / fallback / escalation policy；
• event stream、trace、metrics 与 audit；
• restart recovery 与 orphan run reconciliation。

框架映射

LangGraph

重点映射：State、Node、Edge、Checkpointer、Thread、Interrupt 与 Resume。框架 API 只是入口，真正要理解的是持久状态、事件和恢复语义。

Coding Agent

重点映射：Plan、Execution、Workspace、Tool Session、Commit/Test Evidence、Review、Repair 和 Delivery。只保存聊天历史不足以恢复真实编码任务。

掌握标准

• 能区分 Thread、Run、Step、Event、Trace 与 Checkpoint。
• 能说明恢复时为什么不是“从 Python 那一行继续”。
• 能推演工具执行成功但 Checkpoint 写失败的故障窗口。
• 能设计审批 actor、版本校验与重复 resume 防护。
• 能解释取消传播、并发配额和背压怎样避免资源失控。

Related notes

• Agent Engineering MOC
• Tool Calling Engineering MOC
• Agent Evals MOC