第 20 章：Agent Runtime

本章导读

• 核心问题：企业级 Agent Runtime 需要承担哪些平台职责。
• 关键词：Agent Runtime、Task、Session、EventStore、Context、Tool、Skill、Memory
• 学习产出：把 CI 失败分析纳入可追踪、可恢复、可治理的 Runtime 流程。

1. 本章要解决什么问题

前面章节分别讨论了 Agent 的核心能力：

Context
Tool
Skill
Project Knowledge
Harness
Memory
MCP
Multi-Agent

但在企业中，这些能力不能散落在不同业务代码里。

它们需要一个统一的运行时底座。

这个底座就是 Agent Runtime。

Agent Runtime 要解决的问题是：

如何让 Agent 可运行、可恢复、可观测、可治理、可扩展？

一个真正可生产化的 Agent Runtime 不只是调用模型 API。

它至少要管理：

• Task；
• Session；
• State；
• Context；
• Tool；
• Skill；
• Memory；
• Harness；
• Scheduler；
• Event；
• Policy；
• Observability；
• Security；
• Cost。

本章核心观点是：

Agent Runtime 是让 Agent 从 Demo 进入生产环境的系统底座。

2. 对应 Anthropic 文章

本章主要对应：

• Scaling Managed Agents: Decoupling the brain from the hands
• Effective Harnesses for Long-running Agents

Anthropic 在 Managed Agents 中提出一个非常重要的设计：

Brain
Hands
Session

并强调三者应该解耦。

• Brain：Claude 与 Harness，负责思考、规划和决策；
• Hands：Sandbox 与 Tools，负责执行动作；
• Session：事件日志，负责持久化任务过程。

这对企业 Agent Runtime 非常有启发。

如果 Brain、Hands、Session 绑在一起，系统会很难扩展和恢复。

如果它们解耦，每一部分都可以独立失败、替换和扩展。

3. Agent Runtime 的职责

3.1 Task Management

Task 是用户或系统提交给 Agent 的目标。

例如：

分析 CI 失败原因
为 OrderService 添加单元测试
评审这个 Pull Request
调研是否采用某个框架

Runtime 应负责：

• 创建任务；
• 分类任务；
• 设置优先级；
• 分配 Agent；
• 跟踪状态；
• 处理取消和暂停；
• 输出结果。

3.2 Session Management

Session 是一次 Agent 执行过程。

一个 Task 可以有一个或多个 Session。

Session 应保存：

• 输入；
• 模型消息；
• 工具调用；
• 工具结果；
• 状态变更；
• Checkpoint；
• 错误；
• 用户反馈；
• 最终结果。

重要原则：

Session 不等于模型上下文窗口。

Session 是外部持久化对象。

Context Window 是某一次模型调用看到的内容。

3.3 State Management

Runtime 必须维护状态。

状态包括：

Task State
Session State
Agent State
Tool State
Workspace State
Checkpoint State

状态不能只存在于模型上下文中。

否则进程崩溃、上下文压缩或重启后无法恢复。

3.4 Context Management

Runtime 应统一调用 Context Layer：

ContextProvider
ContextSelector
ContextCompressor
ContextBoundaryPolicy
ContextRenderer

业务 Agent 不应该自己拼接 Prompt。

3.5 Tool Management

Runtime 应统一管理工具：

• 工具注册；
• 工具选择；
• 权限检查；
• 超时；
• 重试；
• 审计；
• 结果压缩。

3.6 Skill Management

Runtime 应根据任务动态加载 Skill。

例如：

任务是写单元测试 → 加载 spring-boot-unit-test skill
任务是 PR Review → 加载 code-review skill
任务是故障排查 → 加载 incident-analysis skill

3.7 Event Management

所有关键动作都应变成事件。

例如：

TASK_CREATED
SESSION_STARTED
CONTEXT_BUILT
MODEL_CALLED
TOOL_CALLED
TOOL_RESULT_RECEIVED
CHECKPOINT_SAVED
VERIFICATION_FAILED
TASK_COMPLETED

事件流是 Agent 可观测性和恢复能力的基础。

4. Agent Runtime 分层

一个企业 Agent Runtime 可以分为：

API Layer
Task Layer
Runtime Core
Context Layer
Tool Layer
Skill Layer
Memory Layer
MCP Layer
State Layer
Observation Layer
Security Layer

每一层都应该有明确边界。

5. Brain、Hands、Session 解耦

Managed Agents 的核心启发是解耦。

5.1 Brain

Brain 包含：

• LLM；
• Harness；
• Planner；
• Reasoning Loop；
• Policy-aware decision。

Brain 不应该直接持有不可恢复状态。

5.2 Hands

Hands 包含：

• 工具执行器；
• 沙箱；
• 文件系统；
• 命令执行；
• 企业系统连接；
• MCP Server。

Hands 可以失败、重建、替换。

5.3 Session

Session 是 durable event log。

即使 Brain 或 Hands 崩溃，Session 仍然保留任务历史。

Runtime 可以通过：

wake(sessionId)
getSession(sessionId)
rebuildState(events)
resume()

恢复任务。

6. 架构图 / 流程图

6.1 Agent Runtime 总览

6.2 Brain / Hands / Session

6.3 Runtime 事件流

7. Java / Spring Boot 落地方案

7.1 AgentRuntime

public interface AgentRuntime {
    AgentTaskResult submit(AgentTask task);
    AgentTaskResult resume(String sessionId);
    void pause(String sessionId);
    void cancel(String sessionId);
}

7.2 AgentTask

public record AgentTask(
    String taskId,
    String userId,
    String objective,
    AgentTaskType type,
    TaskPriority priority,
    Map<String, Object> metadata
) {}

7.3 AgentSessionManager

public interface AgentSessionManager {
    AgentSession create(AgentTask task);
    AgentSession get(String sessionId);
    AgentSession rebuildFromEvents(String sessionId);
    void updateState(String sessionId, AgentSessionState state);
}

7.4 EventStore

public interface AgentEventStore {
    void append(String sessionId, AgentEvent event);
    List<AgentEvent> read(String sessionId);
}

7.5 AgentEvent

public record AgentEvent(
    String eventId,
    String sessionId,
    AgentEventType type,
    Object payload,
    Instant createdAt
) {}

事件类型：

public enum AgentEventType {
    TASK_CREATED,
    SESSION_STARTED,
    CONTEXT_BUILT,
    MODEL_CALLED,
    TOOL_CALLED,
    TOOL_RESULT_RECEIVED,
    CHECKPOINT_SAVED,
    VERIFICATION_PASSED,
    VERIFICATION_FAILED,
    TASK_COMPLETED,
    TASK_FAILED
}

7.6 RuntimePolicy

public record RuntimePolicy(
    int maxIterations,
    Duration timeout,
    BigDecimal maxCost,
    Set<String> allowedTools,
    boolean requireApprovalForWriteActions
) {}

8. 常见误区

8.1 把 Runtime 当模型 API 封装

模型 API Client 只是 Runtime 很小的一部分。

8.2 Session 等于上下文窗口

Session 应是 durable event log，Context Window 只是一次调用的输入。

8.3 状态只存在内存中

生产环境必须持久化状态和事件。

8.4 工具执行与模型推理耦合

Brain 和 Hands 应解耦，便于扩展和恢复。

8.5 没有统一事件流

没有事件流，就没有可观测性、审计和恢复。

9. 贯穿案例：CI 失败分析 Agent

CI 失败分析 Agent 在 Runtime 中的执行流程如下：

CI 失败 webhook
  ↓
TaskManager 创建 AgentTask
  ↓
SessionManager 创建 AgentSession
  ↓
ContextManager 加载 CI 摘要、Git Diff、AGENTS.md
  ↓
SkillManager 加载 ci-failure-analysis Skill
  ↓
ToolOrchestrator 执行只读工具计划
  ↓
Harness 验证报告结构和证据
  ↓
EventStore 保存完整事件
  ↓
返回报告或评论到 Jira / PR

关键事件包括：

TASK_CREATED
SESSION_STARTED
CONTEXT_BUILT
SKILL_LOADED
TOOL_CALLED
TOOL_RESULT_RECEIVED
REPORT_GENERATED
VERIFICATION_PASSED
TASK_COMPLETED

这个案例说明 Agent Runtime 的价值：它把一次看似简单的“分析 CI 日志”任务，变成了可追踪、可恢复、可治理的执行过程。

10. 本章小结

本章讨论 Agent Runtime。

核心结论：

1. Agent Runtime 是让 Agent 生产化的系统底座。
2. Runtime 负责 Task、Session、State、Context、Tool、Skill、Memory、Event。
3. Session 不等于 Context Window，应作为外部持久化事件日志。
4. Brain、Hands、Session 解耦可以提升恢复能力和扩展性。
5. 企业 Runtime 必须内置安全、审计、观测和成本控制。

一句话总结：

Agent Runtime 的价值，是把模型能力包装成一个可运行、可恢复、可治理的软件系统。

11. 实践任务

任务 1：设计 AgentRuntime 接口

定义 submit、resume、pause、cancel。

任务 2：实现 EventStore

用 PostgreSQL 或文件保存 AgentEvent。

任务 3：设计 Session 重建流程

给定 event log，恢复 AgentSession 状态。

任务 4：画 Runtime 架构图

包含 API、Runtime Core、Context、Tool、Skill、Memory、MCP、State、Observability、Security。