[!info] related notes

• 所属 MOC: Agent MOC, Coding Agent MOC
• 前置概念: Agent, Agent 中的 Tool Use
• 并列概念: Orchestration, Agent-Computer Interface (ACI), Agent 中的 Stopping Conditions
• 易混淆概念: AI Agent Memory Layer
• 关系笔记: AI的能力以及对应的协议, Agent 执行闭环

Agent Runtime

一句话定义

Agent Runtime 是包住模型的完整执行环境，负责把”模型会想”变成”系统能跑”。它不只是一个 while loop，而是包含 Run 生命周期、Step 调度、状态管理、Trace 记录、Checkpoint 持久化、超时控制、取消传播、并发管理和权限边界的完整系统。

核心机制 / 工作原理

Runtime 的职责可以分为四层：

1. 生命周期管理

• Run: 一次任务执行的完整实例（从用户输入到最终输出）
• Step: Run 内的单次推理-动作循环（LLM 调用 + 工具执行）
• Run State: 状态机（pending → running → completed/failed/cancelled/timeout）

详见 Run, Step, Run State。

2. 状态与持久化

• Trace: 执行过程的完整记录，用于调试和监控
• Checkpoint: 状态快照，用于中断恢复和 Human-in-the-loop

详见 Trace, Checkpoint。

3. 控制与保护

• 超时控制: 单步超时、整体超时
• 取消传播: 用户取消 → 停止 LLM 生成 → 停止工具执行
• 并发控制: 限制同时进行的 Run 数量
• 背压管理: 工具执行速度不匹配时的流控
• 沙箱: 工具执行的隔离环境
• 权限边界: Agent 可以做什么、不可以做什么

详见 Cancellation, [[sandbox|Sandbox]], Permission Boundary。

4. 事件产出

Runtime 在执行过程中持续产出事件，供前端渲染和后端记录：

• text_delta: 文本增量
• tool_call_start: 工具调用开始
• tool_call_result: 工具执行结果
• progress: 进度更新
• interrupt: 需要人类介入
• error: 错误
• done: 完成
• heartbeat: 心跳保活

详见 Run Event, Heartbeat Event。

与其他组件的关系

Agent Runtime 的核心组成:

┌─────────────────────────────────────────┐
│            Agent Runtime                │
│                                         │
│  ┌────────────┐  ┌────────────────┐    │
│  │ Agent      │  │ LLM Gateway    │    │
│  │ Engine     │  │ (模型调用)      │    │
│  └─────┬──────┘  └────────┬───────┘    │
│        │                  │             │
│  ┌─────▼──────────────────▼───────┐    │
│  │       Tool Runtime             │    │
│  │  Registry · Executor · Sandbox │    │
│  └────────────────────────────────┘    │
│                                         │
│  ┌────────────────────────────────┐    │
│  │     State Manager              │    │
│  │  Run State · Checkpoint        │    │
│  └────────────────────────────────┘    │
│                                         │
│  ┌────────────────────────────────┐    │
│  │     Observability              │    │
│  │  Trace · Metrics · Logging     │    │
│  └────────────────────────────────┘    │
│                                         │
│  ┌────────────────────────────────┐    │
│  │     Control Layer              │    │
│  │  Timeout · Cancel · Concurrency│    │
│  │  Permission · Approval         │    │
│  └────────────────────────────────┘    │
└─────────────────────────────────────────┘

最小例子 / 最小场景

一个 coding agent 调用”运行测试”工具时，runtime 会：

1. 检查权限：当前 Agent 是否有权执行 shell 命令
2. 在沙箱环境中执行命令
3. 捕获退出码和输出
4. 检查超时：如果超过 30s 则终止
5. 把结果写进 Trace
6. 保存 Checkpoint
7. 再把这些反馈送回模型，决定下一步是修代码、继续跑还是停下

在 React + Go + Python 架构中的位置

Runtime 主要在 Python AI Service 层实现：

• Python: Agent Runtime 核心（Run、Step、State、Trace、Checkpoint）
• Go 后端: 调用 Runtime 入口、转发事件、持久化结果
• React 前端: 消费 Runtime 产出的事件、展示执行状态

边界与易混淆点

• Runtime vs Engine: Engine 负责推理逻辑（调 LLM、选工具），Runtime 负责执行环境（生命周期、状态、权限）。在很多框架中两者融合，但在三层架构中应分离。
• Runtime vs Orchestration: Orchestration 更偏流程编排（工作流、状态机），Runtime 范围更大，还包括工具执行、权限控制等。
• Runtime vs Memory: Memory 只是 Runtime 的一层状态来源，不覆盖权限、追踪、工具执行等问题。

Related notes

• Agent MOC
• Agent Runtime MOC — Runtime 知识地图
• Run — 一次任务执行的完整生命周期
• Step — Run 内的单次推理-动作循环
• Trace — 执行过程的完整记录
• Checkpoint — 状态快照与恢复
• Agent Engine — 推理逻辑层
• Agent 执行闭环