Agent Governance Toolkit 解耦式执行与学习架构:DoerAgent 与 ObserverAgent 实现低延迟持久自进化

原创2026-09-17 18:52:061,917 阅读
文章标签:人工智能AI 安全治理可信 AI策略引擎认证鉴权身份认证Agent 沙箱零信任可观测性安全治理

Agent Governance Toolkit 解耦式执行与学习架构:DoerAgent 与 ObserverAgent 实现低延迟持久自进化

导读

本文基于 Agent Governance Toolkit 中 Self-Evolving Agent 示例的落地实现,完整剖析"解耦式执行与学习"(Decoupled Execution and Learning)架构:将"执行者 Doer"与"学习者 Observer"彻底分离,让 Agent 在线响应仅需一次 LLM 调用即可返回,而反思(Reflect)与进化(Evolve)等自改进逻辑全部下沉到离线异步处理,同时保持旧版同步自进化模式的向后兼容。读完本文,你将掌握该架构的组件划分、事件流与检查点机制、环境变量配置、两种使用模式以及无 API Key 的结构化验证方法,并可直接在 self-evaluating 示例目录 中复现全部流程。

架构背景:为什么要分离"执行"与"学习"

Self-Evolving Agent 的传统(Legacy)模式采用同步自改进循环:Task → Act → Reflect → Evolve → Retry。每处理一个请求,Agent 不仅要回答用户问题,还要在同一请求路径上调用反思模型打分、调用进化模型重写系统指令,甚至在分数不达标时循环重试。从 agent.py 的 SelfEvolvingAgent.run 实现 可以看出,单次请求最多会触发 3 次重试,每次重试包含 1 次执行调用、1 次反思调用,累计可达 3-9 次 LLM 调用——用户需要等待"执行 + 反思 + 进化"的完整链路,体验与成本都难以接受。

解耦式架构的核心思想是:低延迟不牺牲学习能力,持久学习不拖累在线路径。DoerAgent 负责执行并即时返回,ObserverAgent 作为"影子学习者"在离线侧消费执行轨迹,二者通过一个追加式事件流解耦。

组件全景:本次实现新增与修改了什么

新增组件(源码佐证)

组件 源码文件 职责
TelemetryEvent / EventStream telemetry.py 执行事件的数据结构与追加式 JSONL 事件流,支持批量读取与基于检查点的增量处理
ObserverAgent observer.py 异步学习 Agent:离线消费事件流,执行反思与进化,更新智慧数据库,基于检查点跟踪进度
DoerAgent agent.py 同步执行 Agent:只读访问智慧数据库,执行时发射遥测,不进行反思与进化,立即返回
example_decoupled.py examples/example_decoupled.py 演示脚本:Phase 1 用 DoerAgent 执行任务,Phase 2 用 ObserverAgent 离线学习
test_decoupled.py tests/test_decoupled.py 测试套件:覆盖 TelemetryEvent/EventStream、DoerAgent/ObserverAgent 的结构化验证,无需 API 调用
verify_architecture.py examples/verify_architecture.py 手动验证脚本:无 API Key 验证全部组件与解耦数据流,并校验向后兼容
ARCHITECTURE_DECOUPLED.md docs/ARCHITECTURE_DECOUPLED.md 详细架构文档:组件描述、数据流、使用模式与设计原则

修改组件

  • agent.py:新增 DoerAgent 类,保留 SelfEvolvingAgent 不动(向后兼容);telemetry 作为可选依赖通过 try/except ImportError 导入;
  • README.md:补充解耦模式文档与使用示例;
  • ARCHITECTURE.md:增加指向 ARCHITECTURE_DECOUPLED.md 的引用,保留旧文档;
  • .gitignore:排除 telemetry_events.jsonl 与 observer_checkpoint.json 两个运行时产物。

执行阶段(Doer):1 次 LLM 调用,立即返回

代码示例

from agent import DoerAgent

# 初始化 Doer
doer = DoerAgent()

# 执行任务(立即返回)
result = doer.run("What is 25 * 4 + 50?")
# 遥测事件自动写入事件流

执行流程与源码对应

对照 agent.py 的 DoerAgent.run 的实现,其流程为:

  1. 加载智慧(只读):self.wisdom = MemorySystem(wisdom_file),Wisdom 数据库只读访问;
  2. 执行查询:self.act(query) 调用 AGENT_MODEL 指定的执行模型生成响应;
  3. 发射遥测:先后通过 _emit_telemetry 发射 task_start 与 task_complete 两类事件,事件携带 query、agent_response、success、instructions_version、conversation_id、turn_number 等字段;
  4. 立即返回:不触发任何反思或进化调用,run() 返回包含 response、instructions_version、telemetry_emitted 的字典。

值得注意的是,DoerAgent 在保留"只执行"核心职责的同时,其构造函数还提供了一系列可插拔的可选能力(详见 agent.py 构造函数):enable_prioritization(优先级框架)、enable_intent_detection(意图检测)、enable_circuit_breaker(熔断器 A/B 分流)、enable_constraint_engine(约束引擎逻辑防火墙)、enable_metadata(OAD 元数据清单)。这些能力均采用"可选导入 + 失败降级"策略,任一模块缺失时打印警告并自动禁用,不影响核心执行路径。

延迟特征:仅 1 次 LLM 调用,即 AGENT_MODEL(默认 gpt-4o-mini)的执行调用。

学习阶段(Observer):离线批量处理,不阻塞执行

代码示例

from observer import ObserverAgent

# 初始化 Observer
observer = ObserverAgent()

# 处理累积的遥测事件(离线)
results = observer.process_events()
# 智慧数据库已根据学到的经验更新

学习流程与源码对应

对照 observer.py 的 process_events 的实现:

  1. 读取未处理事件:基于检查点中的 last_processed_timestamp,通过 EventStream.read_unprocessed() 增量读取;
  2. 逐条分析执行轨迹:对每个 task_complete 事件调用 analyze_trace,内部执行 reflect()——用 REFLECTION_MODEL(默认 gpt-4o-mini)按正确性、完整性、清晰度、工具使用四个维度打分并生成 critique;
  3. 分数低于阈值则进化:若 score < SCORE_THRESHOLD(默认 0.8),调用 evolve() 用 EVOLUTION_MODEL 基于 critique 重写系统指令,并通过 MemorySystem.update_instructions() 写入智慧数据库、递增 version 并记录改进日志;
  4. 更新检查点:处理完毕后将最后一条事件的 timestamp 写入 observer_checkpoint.json,并累计 lessons_learned。

更丰富的学习信号(源码层面的进阶能力)

ObserverAgent 并非只会对 task_complete 做反思打分,从 observer.py 的实现可以看出它还处理三类补充学习信号:

  • 静默信号(Silent Signals):signal_undo(用户撤销动作,评为 0.0 分、critical 优先级)、signal_abandonment(用户中途放弃,评为 0.3 分、high 优先级)、signal_acceptance(用户接受输出,评为 1.0 分、正向强化),通过 analyze_signal 判定并学习;
  • 意图驱动评估(Intent-Based Evaluation):通过 evaluate_conversation_by_intent 对多轮会话按意图分类评估——troubleshooting 场景超过 3 轮视为失败(用户被困),brainstorming 场景上下文过浅视为失败,相关意图字段 intent_type、intent_confidence 由 DoerAgent 在首轮通过 IntentDetector 检测并写入事件;
  • 智慧策展(Wisdom Curator):可选启用时,进化产生的指令若触发策略违规检测(如安全、隐私、质量模式),则创建人工审批工单而非自动应用,实现 human-in-the-loop 的高层策展。

process_events 的返回值包含 events_processed、lessons_learned、analyses、signal_stats、intent_evaluations、curator_stats 等统计结构,便于接入监控与告警。

延迟特征:离线执行,不阻塞在线响应;可以按 cron 或后台任务批量调度。

智慧数据库与事件流的数据结构

Wisdom Database(system_instructions.json)

由 MemorySystem 管理,每次进化递增 version 并追加 improvements 记录:

{
  "version": 2,
  "instructions": "Current system prompt text",
  "improvements": [
    {
      "version": 2,
      "timestamp": "2024-01-01T12:00:00",
      "critique": "What was learned from failure",
      "query": "触发改进的原始查询(可选)",
      "response": "触发改进的原始响应(可选)"
    }
  ]
}

Event Stream(telemetry_events.jsonl)

由 EventStream 管理的追加式 JSONL 日志,每行一条事件:

{"event_type":"task_start","timestamp":"2024-01-01T12:00:00","query":"...","instructions_version":1}
{"event_type":"task_complete","timestamp":"2024-01-01T12:00:01","query":"...","agent_response":"...","success":true,"instructions_version":1}

TelemetryEvent 数据类(telemetry.py)的核心字段包括:event_type(task_start、task_complete、user_feedback、signal_undo、signal_abandonment、signal_acceptance)、timestamp、query、agent_response、success、user_feedback、instructions_version、metadata、signal_type、signal_context,以及意图评估扩展字段 conversation_id、turn_number、intent_type、intent_confidence。EventStream 提供 emit、read_all、read_unprocessed、clear、get_last_timestamp、get_signal_events、get_conversation_events、get_conversation_turn_count 等方法,支持批量读取、检查点增量消费与会话维度查询。

环境变量配置

两种模式共享同一组环境变量,默认值以源码实际实现为准:

环境变量 作用 默认值
OPENAI_API_KEY OpenAI API 密钥(必需,通过 .env 文件加载) 无
AGENT_MODEL 执行模型(DoerAgent 与 SelfEvolvingAgent 均使用) gpt-4o-mini
REFLECTION_MODEL 反思打分模型 gpt-4o-mini
EVOLUTION_MODEL 指令进化模型 gpt-4o-mini
SCORE_THRESHOLD 学习触发阈值(分数低于该值触发进化) 0.8
MAX_RETRIES Legacy 模式最大重试次数 3

从 observer.py 的源码可以看出,学习侧模型通过 os.getenv("REFLECTION_MODEL", "gpt-4o-mini") 与 os.getenv("EVOLUTION_MODEL", "gpt-4o-mini") 独立配置,这正体现了"执行与学习可以使用不同模型"的架构灵活性——线上执行可以用低成本低延迟模型,离线学习则可以用更强的模型。

关键收益

  1. 低运行时延迟:Doer 立即返回(1 次 LLM 调用,对比 Legacy 模式的 3-9 次);
  2. 持久学习:Observer 随时间在智慧数据库中持续累积经验;
  3. 可扩展性:Observer 可以批量处理事件,学习与执行解耦后可独立水平扩展;
  4. 灵活性:执行与学习可以使用不同的模型与资源配置;
  5. 异步处理:学习在离线侧完成,不占用用户等待时间;
  6. 向后兼容:Legacy 模式(SelfEvolvingAgent)原样保留,example.py 依旧可用。

解耦模式与 Legacy 模式架构对比

方面 解耦模式 Legacy 模式
执行延迟 低(1 次 LLM 调用) 高(1-3 轮迭代,共 3-9 次 LLM 调用)
学习方式 异步、离线 同步、执行期间
重试 无(从遥测中学习) 最多 3 次立即重试
用户等待 仅执行 执行 + 反思 + 进化
可扩展性 高(批量处理) 低(按请求)
模型选择 执行与学习可分别配置 全程同一模型

使用方式

快速开始(解耦模式)

# 安装依赖
pip install -r requirements.txt

# 配置环境变量(在 self-evaluating 目录下)
cp .env.example .env
# 编辑 .env,填入 OPENAI_API_KEY

# 运行解耦示例
python example_decoupled.py

手动使用

# Phase 1: 执行(快速)
from agent import DoerAgent
doer = DoerAgent()
result = doer.run(query)

# Phase 2: 学习(离线)
from observer import ObserverAgent
observer = ObserverAgent()
observer.process_events()

生产推荐模式:连续执行 + 定时学习

# Web 服务或 API 侧——快速响应
doer = DoerAgent()
response = doer.run(user_query)  # 立即返回
return response

# Cron 任务或后台 worker——离线学习
observer = ObserverAgent()
observer.process_events()  # 批量处理遥测

Legacy 模式(仍然可用)

python example.py

无 API Key 的验证方式

解耦架构的验证不依赖真实 LLM 调用,仓库提供了两条无成本验证路径:

  1. 结构化测试套件 tests/test_decoupled.py:覆盖 TelemetryEvent 的序列化/反序列化、EventStream 的发射/全量读取/增量读取/末时间戳/清空、DoerAgent 与 ObserverAgent 的初始化与检查点持久化/加载,全程不发起 API 调用;
  2. 手动验证脚本 examples/verify_architecture.py:六步验证流程——遥测系统读写、DoerAgent 初始化、ObserverAgent 初始化、事件流读取、五大组件结构核对、SelfEvolvingAgent 向后兼容性确认。

运行方式(在 self-evaluating 目录 下):

python tests/test_decoupled.py
python examples/verify_architecture.py

扩展点与设计原则

从 ARCHITECTURE_DECOUPLED.md 可以归纳出系统的七大设计原则:关注点分离(执行与学习解耦)、低延迟(关键路径开销最小化)、持久记忆(智慧随时间累积)、可扩展(学习可批量与定时)、灵活(不同阶段可用不同模型/资源)、向后兼容(Legacy 模式保留)、可观测(遥测提供完整审计轨迹)。

同时系统预留了明确的扩展点:文件存储可替换为数据库;可为遥测添加自定义分析器;可实现替代学习算法;可按条件选择模型;可为 AgentTools 增加更多工具;可将用户反馈接入学习回路;还可运行多个 Observer 实现分布式并行处理。

安全与结论

仓库的实现总结明确记录了安全验证结果:未发现漏洞、全部安全检查通过、无敏感数据暴露、API 密钥通过环境变量妥善处理(dotenv 加载 .env,源码中未硬编码密钥)。

总而言之,该实现通过"执行与学习解耦"的架构演进,在保持 SelfEvolvingAgent 完整向后兼容的前提下,将在线路径的 LLM 调用压缩到 1 次,同时把反思、进化、静默信号、意图评估、策略策展等学习能力全部沉淀到离线侧,配合追加式事件流与检查点机制,形成了一套可调度、可扩展、可观测、带完整测试与验证脚本的生产级自进化 Agent 参考实现。若要接入真实 OpenAI API,只需创建 .env 写入 OPENAI_API_KEY,运行 python example_decoupled.py,即可观察 DoerAgent 快速执行、ObserverAgent 离线学习并持续累积智慧版本的全过程。

登录后查看全文
agent-governance-toolkit