# Controlled Agent Runtime：构建可观测、可回放的受控多智能体工作流运行时

> 一个面向生产环境的多智能体运行时框架，通过ActorView实现感知隔离、DomainEvent确保状态安全、Golden Replay支持回归测试，以Hazard Lab场景展示隐藏信息处理、委托动作、长时记忆等复杂交互。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-01T06:15:48.000Z
- 最近活动: 2026-06-01T06:26:03.271Z
- 热度: 163.8
- 关键词: Agent运行时, 多智能体, 事件溯源, LangGraph, 可观测性, 回归测试, ActorView, DomainEvent, Golden Replay, 状态管理
- 页面链接: https://www.zingnex.cn/forum/thread/controlled-agent-runtime
- Canonical: https://www.zingnex.cn/forum/thread/controlled-agent-runtime
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**: yukinorin775780
- **来源平台**: GitHub
- **原始标题**: Controlled Agent Sim Runtime
- **原始链接**: https://github.com/yukinorin775780/controlled-agent-runtime-ai-rd
- **发布时间**: 2026年6月

---

## 背景：为什么Agent需要"受控"运行时

大语言模型（LLM）Agent的爆发式发展带来了前所未有的自动化能力，但也暴露出一个核心矛盾：**模型的开放性与生产环境所需的确定性之间的矛盾**。

LLM本质上是概率性的——同样的输入可能产生不同的输出，这种特性在创意写作或头脑风暴场景中是优势，但在需要精确状态管理的生产系统中却是风险来源。当Agent被赋予调用工具、修改数据库、发送邮件等能力时，"不受控"的行为可能导致严重后果。

业界目前的Agent框架（如LangChain、AutoGPT、OpenAI Assistants API等）大多采用"提示工程+工具调用"的范式，将大量责任委托给模型的"理解能力"。这种方式在原型阶段运行良好，但在规模化部署时面临几个根本挑战：

首先是**状态一致性**。如果Agent在一次对话中修改了数据库记录，如何确保这个修改是可预期的、可审计的、可回滚的？其次是**可见性**。当Agent做出一个决策时，开发者能否准确理解它"看到"了什么信息、"考虑"了哪些因素？第三是**可测试性**。如何在不调用昂贵LLM API的情况下，对Agent行为进行回归测试？

Controlled Agent Runtime项目正是为回答这些问题而设计。

---

## 核心理念：分离意图与执行

项目的核心架构原则可以用一句话概括：**LLM负责意图解释和表达，确定性系统负责状态变更**。

这种分离不是简单的"LLM生成代码，然后执行"，而是更深层次的架构边界设计：

### 意图层（Intent Layer）

LLM-facing节点负责：
- 理解用户输入的意图
- 生成自然语言回复和"表达"（barks）
- 提出状态变更的"建议"

这一层充分利用了LLM的语言理解和生成能力，但不直接操作任何系统状态。

### 执行层（Execution Layer）

确定性系统负责：
- 移动、检查、库存管理等游戏机制
- 状态变更的最终提交
- 事件溯源和持久化
- 可重放的执行记录

这一层确保所有状态变更都是可预测、可测试、可审计的。

### 事件层（Event Layer）

连接两层的是强类型的`DomainEvent`系统。所有状态变更必须通过事件表示，事件通过`EventDrain`统一处理。这种设计带来了几个好处：

- **统一接口**：无论变更来自哪个Agent或哪个系统，都通过相同的事件机制处理
- **可序列化**：事件可以持久化、传输、回放
- **可审计**：完整的事件日志就是系统的审计追踪
- **可测试**：可以构造事件序列进行回归测试，无需调用LLM

---

## 关键架构组件

### ActorView：感知隔离

`ActorView`是项目中最精妙的设计之一。它解决了多Agent系统中一个常见问题：**每个Agent应该"看到"什么信息？**

在现实世界的多Agent场景中，信息往往是分布式的、不对称的。一个Agent可能知道某些信息，另一个Agent可能不知道；某些信息是公开的，某些是私密的。传统的"把所有上下文都给LLM"的做法既不高效（token浪费）也不安全（信息泄露）。

`ActorView`通过以下机制实现精细的感知控制：

- **世界状态过滤**：根据Agent的位置、能力、角色，过滤可见的世界对象
- **历史记录裁剪**：只提供该Agent有权访问的历史事件
- **私有记忆注入**：每个Agent有自己的记忆服务，存储学习到的知识
- **同伴状态可见性**：控制Agent能看到哪些其他Agent的状态

这种设计使得"隐藏信息"成为系统的一等公民。在Hazard Lab演示场景中，Scout Agent能够检测到隐藏的毒气陷阱，而其他Agent看不到——这不是通过prompt告诉LLM"假装你看不到"，而是真正的信息隔离。

### DomainEvent与EventDrain

`DomainEvent`是系统中所有状态变更的载体。它采用强类型设计，每个事件类型都有明确的schema：

```python
class ItemPickedUp(DomainEvent):
    actor_id: str
    item_id: str
    location: Location
    timestamp: datetime
```

`EventDrain`是事件的统一处理中心：

- 接收来自各个系统的事件
- 按顺序应用到游戏状态
- 生成状态检查点（checkpoint）
- 触发副作用（如UI更新、持久化）

这种事件溯源（Event Sourcing）架构使得系统状态完全可重建——给定初始状态和事件序列，可以精确重现任何时刻的系统状态。

### Golden Replay Eval

这是项目最具工程价值的特性之一。传统的Agent测试需要调用LLM API，既昂贵又缓慢（而且非确定性）。Golden Replay Eval通过以下方式解决这个问题：

1. 录制真实运行产生的事件序列（golden case）
2. 在测试时重放这些事件，验证系统行为是否一致
3. 断言最终状态、中间状态、路由决策是否符合预期

项目当前包含50个golden replay测试用例，全部通过。这些测试覆盖了：

- 路由决策（Director Router）
- 记忆隔离（Memory Isolation）
- 物品转移（Item Transfer）
- 危险处理（Hazard Handling）
- 场景结果（Scenario Outcomes）

重要的是，这些测试可以在不调用任何LLM的情况下运行，提供了真正的回归测试能力。

### LangGraph运行时

项目基于LangGraph构建Agent工作流，但做了重要的定制：

- **显式路由**：Director Router根据输入类型决定进入哪个处理分支
- **状态机语义**：每个节点有明确的输入/输出契约
- **可观测性**：每个阶段的决策、payload、状态变更都可记录和检查

与直接使用LangChain的"链式"API不同，这种显式图结构更适合复杂的多Agent协作场景。

---

## Hazard Lab：垂直切片演示

项目包含一个名为Hazard Lab的演示场景，设计目的是"压力测试"运行时基础设施。这个场景虽小，但涵盖了多个关键挑战：

### 场景设定

团队在一个密封设施中醒来，需要通过协作逃脱。场景包含：

1. **隐藏信息**：毒气陷阱对普通Agent不可见
2. **委托动作**：玩家可以将开锁、解除陷阱等动作委托给特定Agent
3. **长时记忆**：Analyst Agent需要阅读实验室笔记并更新共享知识
4. **确定性提交**：钥匙转移必须通过事件系统正式提交
5. **可观测后果**：Gatekeeper的响应会根据之前发现的证据而变化

### 多Agent角色设计

场景中的三个Agent各有特色：

| Agent | 角色 | 特殊能力 |
|-------|------|----------|
| Scout | 侦察兵 | 能检测隐藏陷阱和环境线索 |
| Analyst | 分析师 | 能解读文档、更新共享知识库 |
| Tactician | 战术家 | 擅长战斗策略和团队协调 |

这种差异化设计不是装饰性的——它展示了运行时如何支持"不同Agent有不同感知、记忆、风险偏好"的复杂场景。

### 演示的教育价值

Hazard Lab的意图不是成为一个完整的游戏，而是成为一个**可教学的例子**。通过这个小场景，开发者可以理解：

- 为什么需要`ActorView`以及它如何工作
- 事件系统如何保证状态一致性
- Golden Replay如何支持回归测试
- 运行时边界如何防止LLM越权

---

## Web全栈与可观测性

项目包含完整的Web演示界面，这是"可观测性"理念的具体体现。

### 技术栈

- **后端**：FastAPI提供REST API（`/api/chat`、`/api/state`）
- **运行时**：LangGraph处理Agent工作流
- **前端**：原生JavaScript渲染地图、时间线、状态检查器

### Director Timeline

这是Web UI的核心组件，展示了Agent决策的完整时间线：

- 每个决策点显示路由选择（为什么走这条分支）
- 显示Agent接收到的`ActorView`（它"看到"了什么）
- 显示生成的payload（LLM的原始输出）
- 显示应用的状态变更（通过EventDrain提交的事件）

这种可视化使得"黑盒"Agent变得可理解、可调试。

### State Diff与Payload Inspector

- **State Diff**：对比操作前后的状态变化，精确显示哪些字段被修改
- **Payload Inspector**：查看LLM生成的原始输出，包括思考过程（如果模型支持）

这些工具对于理解Agent行为、调试意外结果至关重要。

---

## 工程证据与质量保证

项目采用"命令支持的证据"而非"截图或主观演示声明"来展示质量。

### 当前测试状态

| 测试类型 | 结果 |
|---------|------|
| Python单元测试 | 460 passed |
| Golden Replay Eval | 50/50 passed |
| Web UI测试 | 285 passed |
| Benchmark Dry-run | 4 cases selected |

### 可复现性

运行以下命令即可生成本地证据报告：

```bash
python scripts/generate_evidence_report.py
```

这种"证据即代码"的做法确保了项目声明的可验证性。

### Benchmark工具

项目包含性能benchmark工具，比较：

- 图路由+范围prompt（项目方案）vs 朴素全状态Agent（基线）

这种对比对于理解架构设计的实际价值很有帮助。

---

## 项目边界与定位

作者明确界定了项目的范围，这体现了良好的工程判断力：

### 不是什么

- **不是模型训练项目**：不涉及微调LLM或训练专用模型
- **不是内容繁重的游戏**：Hazard Lab是教学场景，不是商业游戏

### 是什么

- **Agent基础设施原型**：展示如何构建受控、可观测、可测试的Agent运行时
- **工程决策的可见化**：让每个架构选择（为什么隔离感知、为什么事件溯源）都能被理解和评估

这种清晰的定位帮助潜在用户正确设定期望——如果你需要一个即插即用的游戏引擎，这不是合适的选择；如果你想学习如何构建生产级的Agent系统，这正是你需要的参考。

---

## 与现有方案的对比

| 维度 | Controlled Agent Runtime | LangChain | AutoGPT |
|------|-------------------------|-----------|---------|
| 状态管理 | 事件溯源+显式提交 | 通常内嵌在chain中 | 文件系统/向量存储 |
| 感知隔离 | ActorView（一等公民） | 需自行实现 | 无原生支持 |
| 回归测试 | Golden Replay（50+ cases） | 依赖集成测试 | 难以测试 |
| 可观测性 | Director Timeline+State Diff | 依赖回调/日志 | 日志为主 |
| 多Agent | 原生支持角色差异化 | 需额外构建 | 支持但简单 |
| 确定性 | 强（事件驱动） | 中等 | 弱 |

项目的优势在于**工程完整性**——它不是某个特性的演示，而是一个可运行、可测试、可观测的完整系统。

---

## 潜在应用场景

虽然项目以游戏场景演示，但其架构设计适用于多种生产环境：

### 企业自动化工作流

- 不同部门的Agent有不同的数据访问权限（ActorView）
- 所有操作通过事件日志审计（EventDrain）
- 工作流变更可回归测试（Golden Replay）

### 客服机器人系统

- 一线客服Agent只能访问公开知识库
- 升级后的专家Agent可以访问客户历史记录
- 所有对话事件可重放用于质检

### 复杂决策支持

- 多个专业Agent（财务、法律、运营）协作分析
- 每个Agent只看到与其专业相关的信息
- 最终决策基于所有Agent的输入，但由确定性系统执行

---

## 总结

Controlled Agent Runtime是一个高质量的Agent基础设施项目，展示了如何将LLM的开放性与生产系统所需的确定性结合起来。通过清晰的架构边界（意图vs执行）、精细的感知控制（ActorView）、强类型的事件系统（DomainEvent）和可重放的测试框架（Golden Replay），项目为构建可信赖的Agent系统提供了可行的工程路径。

Hazard Lab演示场景虽小，但设计精妙，涵盖了隐藏信息、委托动作、长时记忆、状态提交等关键挑战。配合完善的Web UI和Director Timeline，项目不仅是代码参考，更是学习材料。

对于正在设计或评估Agent架构的工程师来说，这个项目值得深入研究。它的设计决策、工程实践、测试策略都体现了对生产环境的深刻理解。