Agent Governance Toolkit 解耦式执行与学习架构:DoerAgent 与 ObserverAgent 实现低延迟持久自进化
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 的实现,其流程为:
- 加载智慧(只读):
self.wisdom = MemorySystem(wisdom_file),Wisdom 数据库只读访问; - 执行查询:
self.act(query)调用AGENT_MODEL指定的执行模型生成响应; - 发射遥测:先后通过
_emit_telemetry发射task_start与task_complete两类事件,事件携带query、agent_response、success、instructions_version、conversation_id、turn_number等字段; - 立即返回:不触发任何反思或进化调用,
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 的实现:
- 读取未处理事件:基于检查点中的
last_processed_timestamp,通过EventStream.read_unprocessed()增量读取; - 逐条分析执行轨迹:对每个
task_complete事件调用analyze_trace,内部执行reflect()——用REFLECTION_MODEL(默认gpt-4o-mini)按正确性、完整性、清晰度、工具使用四个维度打分并生成 critique; - 分数低于阈值则进化:若
score < SCORE_THRESHOLD(默认 0.8),调用evolve()用EVOLUTION_MODEL基于 critique 重写系统指令,并通过MemorySystem.update_instructions()写入智慧数据库、递增version并记录改进日志; - 更新检查点:处理完毕后将最后一条事件的
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") 独立配置,这正体现了"执行与学习可以使用不同模型"的架构灵活性——线上执行可以用低成本低延迟模型,离线学习则可以用更强的模型。
关键收益
- 低运行时延迟:Doer 立即返回(1 次 LLM 调用,对比 Legacy 模式的 3-9 次);
- 持久学习:Observer 随时间在智慧数据库中持续累积经验;
- 可扩展性:Observer 可以批量处理事件,学习与执行解耦后可独立水平扩展;
- 灵活性:执行与学习可以使用不同的模型与资源配置;
- 异步处理:学习在离线侧完成,不占用用户等待时间;
- 向后兼容: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 调用,仓库提供了两条无成本验证路径:
- 结构化测试套件 tests/test_decoupled.py:覆盖 TelemetryEvent 的序列化/反序列化、EventStream 的发射/全量读取/增量读取/末时间戳/清空、DoerAgent 与 ObserverAgent 的初始化与检查点持久化/加载,全程不发起 API 调用;
- 手动验证脚本 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 离线学习并持续累积智慧版本的全过程。