Self-Evolving Agent 架构解析:从同步自改进循环到 Doer/Observer 解耦执行与学习的完整实践指南
Self-Evolving Agent 架构解析:从同步自改进循环到 Doer/Observer 解耦执行与学习的完整实践指南
本文以 agent-governance-toolkit 仓库中 agent-governance-python/agent-os/examples/self-evaluating 示例框架为核心,深入拆解"自进化 Agent"(Self-Evolving Agent)的两种运行模式:同步自改进循环(Legacy Mode)与解耦式执行/学习架构(Decoupled Mode)。读完本文,你将掌握 Act–Reflect–Evolve 三段式 LLM 调用链路的实现原理、system_instructions.json 智慧库的版本化演进机制、DoerAgent 与 ObserverAgent 的职责划分,以及如何通过环境变量与事件流把"低延迟执行"与"离线批量学习"无缝组合到生产环境。
系统总览:两种运行模式
Self-Evolving Agent 支持两种运行模式:
- Decoupled Mode(解耦模式,推荐):将执行与学习分离——
DoerAgent同步执行任务并即时返回,ObserverAgent异步消费遥测事件、离线学习。详细架构见 ARCHITECTURE_DECOUPLED.md。 - Legacy Mode(传统模式,文档主体):传统的同步自我改进循环,同一进程内依次完成 Act(执行)、Reflect(反思)、Evolve(进化),并在必要时重试。
两种模式共用同一套核心组件:MemorySystem(智慧库)、AgentTools(工具集)、OpenAI API 客户端,以及持久化文件 system_instructions.json。传统模式在 src/agent.py 中以 SelfEvolvingAgent 类保留,用于向后兼容;推荐的新项目直接使用 DoerAgent + ObserverAgent。
传统模式组件架构
传统模式的核心是 SelfEvolvingAgent,其组件关系如下:
┌─────────────────────────────────────────────────────────────┐
│ SelfEvolvingAgent │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Memory │ │ AgentTools │ │ OpenAI API │ │
│ │ System │ │ │ │ Client │ │
│ └─────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ system_instructions.json │ │
│ │ { │ │
│ │ "version": 1, │ │
│ │ "instructions": "...", │ │
│ │ "improvements": [...] │ │
│ │ } │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
MemorySystem:版本化智慧库
MemorySystem(src/agent.py)负责系统指令的持久化与管理,公开四个核心方法:
class MemorySystem:
load_instructions() → dict # 从 JSON 加载,文件缺失或损坏时回退到默认指令(version=1)
save_instructions(dict) → None # 以 indent=2 写回 JSON
get_system_prompt() → str # 取当前 instructions 文本
update_instructions(new_text, critique) → None # 版本号 +1,追加改进记录
update_instructions 的实现细节:每次更新都会令 version 自增,并把 {version, timestamp, critique} 追加到 improvements 数组;若调用时传入 query 与 response,还会一并写入改进记录,为后续"升级清理(upgrade purge)"策略提供失败现场。system_instructions.json 的标准格式为:
{
"version": 2,
"instructions": "Current system prompt text",
"improvements": [
{
"version": 2,
"timestamp": "2024-01-01T12:00:00",
"critique": "What was wrong that led to this update"
}
]
}
仓库自带的初始文件 system_instructions.json 为 version 1,指令内容为"有帮助的 AI 助手 + 逐步思考 + 简洁清晰回答",improvements 为空数组。
AgentTools:Agent 可用的工具集
AgentTools(src/agent.py)目前提供四个静态工具:
calculate(expression)—— 基于 Pythonast解析的数学表达式求值,仅允许+ - * / ** 一元负号等安全操作符,非法表达式(如import os)会返回错误而非执行,从实现上杜绝任意代码执行风险;get_current_time()—— 返回当前日期时间;string_length(text)—— 返回字符串长度;get_available_tools()—— 列出全部可用工具。
在 tests/test_agent.py 中,calculate("2 + 2") 断言包含 "4",calculate("import os") 断言包含 "Error",验证了工具的安全边界;同一测试文件还断言了 MemorySystem 的版本自增与 JSON 持久化行为。
传统模式执行流程:run(query) 主循环
SelfEvolvingAgent.run(query) 是传统模式的入口,最多重试 max_retries(默认 3)次,每次尝试经历 ACT → REFLECT → EVOLVE 三个阶段:
START
│
├──► Attempt 1
│ │
│ ├──► TASK: Receive query from user
│ │
│ ├──► ACT: Agent processes query
│ │ • Load system instructions from JSON
│ │ • Add tool information to context
│ │ • Call LLM to generate response
│ │ • Return agent response
│ │
│ ├──► REFLECT: Evaluate response
│ │ • Call reflection LLM with query + response
│ │ • Get score (0-1) and critique
│ │
│ ├──► Check score >= 0.8?
│ │ │
│ │ ├─YES─► SUCCESS! Return results
│ │ │
│ │ └─NO──► EVOLVE
│ │ • Call evolution LLM with critique
│ │ • Generate new system instructions
│ │ • Save to JSON with version++
│ │ • Log improvement
│ │
├──► Attempt 2 (with evolved instructions)
│ │
│ └──► [Same flow as Attempt 1]
│
├──► Attempt 3 (with further evolved instructions)
│ │
│ └──► [Same flow as Attempt 1]
│
└──► Max retries reached
• Return best attempt
• Mark as failure if score < 0.8
从源码看(src/agent.py),每次尝试的结果(attempt 序号、response、score、critique、instructions_version)都会存入 results["attempts"];一旦 score >= score_threshold 立即返回成功;全部重试用尽后,返回得分最高的那次响应并标记 success=False。整个循环天然具备"有界重试 + 阈值判定 + 审计轨迹"三个特性。
LLM Call 1:Act 阶段(任务执行)
Input:
• System: Current instructions + Tool descriptions
• User: Query
Processing:
• LLM analyzes query
• Determines if tools are needed
• Generates response
Output:
• Agent response (string)
实现上,act() 把系统指令与工具描述拼接为完整 system prompt,并追加一句"如需使用工具,请说明将使用哪个工具及原因",然后以 temperature=0.7 调用 AGENT_MODEL。模型默认 gpt-4o-mini。
LLM Call 2:Reflect 阶段(响应评估)
Input:
• Query: Original user question
• Response: Agent's answer
• Criteria: Correctness, Completeness, Clarity, Tool Usage
Processing:
• Evaluator LLM scores response
• Generates detailed critique
• Returns as JSON
Output:
• score: float (0-1)
• critique: string
reflect()(src/agent.py)使用独立的反思模型,从四个维度评估:正确性(Correctness)、完整性(Completeness)、清晰度(Clarity)、工具使用(Tool Usage)。评估提示词要求模型只返回合法 JSON:{"score": 0.85, "critique": "..."},代码会剥离可能包裹的 markdown 代码块再解析;若解析失败,回退为 score=0.5 并记录反思错误,避免单点故障中断主循环。反思调用使用较低温度 0.3,以保证评分稳定。
LLM Call 3:Evolve 阶段(指令进化)
Input:
• Current instructions
• Recent query & response
• Critique explaining issues
Processing:
• Evolution LLM analyzes critique
• Identifies what to improve
• Rewrites system instructions
Output:
• new_instructions: string
Side Effect:
• Updates system_instructions.json
• Increments version number
• Logs improvement history
evolve()(src/agent.py)扮演"元学习系统"角色,读取当前指令、最近查询、Agent 响应与批评文本,输出纯文本的新系统指令(无 JSON、无格式化),温度 0.7。进化失败时返回原指令不变,保证系统不会因 LLM 故障而丢失已有智慧。随后 memory.update_instructions(...) 完成版本自增与历史记录。
完整示例执行:数学查询的自进化过程
以文档中的经典场景为例,直观展示一次完整的自进化闭环:
- 初始指令(v1):
"You are a helpful AI assistant. Provide accurate responses." - 查询:
"What is 15 * 24 + 100?"
Attempt 1:
- Act:
"15 times 24 is 360, plus 100 equals 460."(结果正确,但未提及工具) - Reflect:得分 0.6;批评:"Agent 计算正确,但没有提及计算器工具。Agent 应在工具可用且适用时明确说明。"
- Evolve:根据批评生成新指令。
进化后的指令(v2):
"You are a helpful AI assistant with access to tools. When you have a
calculation tool available, always mention it explicitly and explain
that you would use it. Be clear about which tools apply to each query."
Attempt 2:
- Act:
"I can use the calculate() tool for this. Let me solve 15 * 24 + 100. The result would be 460." - Reflect:得分 0.9,达到阈值,成功返回。✓
这个例子清晰展示了"从失败中学习"的价值:第二次尝试不仅答案正确,行为模式(显式说明工具使用)也更符合评估标准,而这些改进被持久化进了 system_instructions.json 的 v2,未来所有同类查询都会受益。
解耦模式:Doer/Observer 分离执行与学习
解耦模式将"执行者(Doer)"与"学习者(Observer)"彻底分离,核心目标依次是:低运行延迟(Doer 不等待学习)、持久学习(Observer 随时间积累智慧)、可扩展(Observer 批量消费事件)、灵活(执行与学习可用不同模型)。
架构图
┌────────────────────────────────────────────────────────────────┐
│ EXECUTION PHASE │
│ (Synchronous - Low Latency) │
├────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌─────────────────┐ │
│ │ DoerAgent │ ─READ─► │ Wisdom Database │ │
│ │ │ │ (Read-Only) │ │
│ └──────┬───────┘ └─────────────────┘ │
│ │ │
│ │ EMIT │
│ ▼ │
│ ┌──────────────┐ │
│ │ Event Stream │ │
│ │ (telemetry) │ │
│ └──────────────┘ │
└────────────────────────────────────────────────────────────────┘
▼ (Asynchronous)
┌────────────────────────────────────────────────────────────────┐
│ LEARNING PHASE │
│ (Asynchronous - Offline) │
├────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ ObserverAgent │◄CONSUME│ Event Stream │ │
│ │ (Shadow Learner)│ │ (telemetry) │ │
│ └────────┬─────────┘ └──────────────────┘ │
│ │ │
│ │ ANALYZE → REFLECT → EVOLVE │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Wisdom Database │ │
│ │ (Read-Write) │ │
│ └─────────────────┘ │
└────────────────────────────────────────────────────────────────┘
数据结构与组件职责
- Wisdom Database(
system_instructions.json):结构与传统模式相同,version + instructions + improvements,由 Observer 独占写权限。 - Event Stream(
telemetry_events.jsonl):追加式 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}
- DoerAgent(src/agent.py):同步执行器。
act(query)用当前智慧执行任务;run(query)主流程发射task_start/task_complete遥测事件后立即返回,不做反思、不学习、不重试。它还可以选配意图检测、优先化框架、熔断器(A/B 流量切分)、约束引擎(逻辑防火墙)与 OAD 元数据清单等扩展能力。 - ObserverAgent(src/observer.py):异步学习者。
reflect(query, response)评估质量,evolve(critique, query, response)生成改进指令,analyze_trace(event)分析单条执行轨迹,learn_from_analysis(analysis)更新智慧库,process_events()是主学习循环——从检查点(checkpoint)之后消费未处理事件,批量执行 ANALYZE → REFLECT → EVOLVE,最后更新observer_checkpoint.json保存进度。 - EventStream / TelemetryEvent(src/telemetry.py):
emit()追加事件,read_all()/read_unprocessed(timestamp)支持断点续读;TelemetryEvent支持task_start、task_complete、user_feedback,并扩展出conversation_id、turn_number、intent_type等字段以支撑多轮对话与意图评估。
两种模式对比
| 维度 | Decoupled 模式 | Legacy 模式 |
|---|---|---|
| 执行延迟 | 低(1 次 LLM 调用) | 高(1-3 次迭代,3-9 次 LLM 调用) |
| 学习方式 | 异步、离线 | 同步、执行期间 |
| 重试 | 无(从遥测中学习) | 最多 3 次即时重试 |
| 用户等待时间 | 仅执行 | 执行 + 反思 + 进化 |
| 可扩展性 | 高(批量处理) | 低(逐请求) |
| 模型 | 执行与学习可用不同模型 | 各阶段可用不同模型(传统模式也支持分模型) |
两种使用模式示例
模式一:连续执行 + 定时学习(推荐)
# Web server or API - fast responses
doer = DoerAgent()
response = doer.run(user_query) # Returns immediately
return response
# Cron job or background worker - learns offline
observer = ObserverAgent()
observer.process_events() # Batch process telemetry
模式二:即时反馈闭环(Legacy)
# All-in-one synchronous mode
agent = SelfEvolvingAgent()
results = agent.run(query) # Includes reflection + evolution
完整的可运行示例见 examples/example_decoupled.py:它先以 3 条查询驱动 DoerAgent 执行并发射遥测,再以 ObserverAgent.process_events() 离线消费事件,最后打印两种模式各自的执行/学习统计。
环境变量配置
两种模式共用一套环境变量控制行为:
OPENAI_API_KEY=sk-... # 必填:OpenAI API 密钥
AGENT_MODEL=gpt-4o-mini # 执行模型(Act 阶段)
REFLECTION_MODEL=gpt-4o-mini # 反思模型(Reflect 阶段,建议低温)
EVOLUTION_MODEL=gpt-4o-mini # 进化模型(Evolve 阶段)
SCORE_THRESHOLD=0.8 # 成功阈值(score >= 0.8 视为成功)
MAX_RETRIES=3 # 最大尝试次数(传统模式有界重试)
从源码确认:SelfEvolvingAgent 与 ObserverAgent 均从环境变量读取模型与阈值(src/agent.py、src/observer.py),且各阶段可使用不同模型——解耦模式下 Observer 可以选用更强、更贵的模型做离线学习,而不影响线上执行延迟。
关键设计原则
- 关注点分离:三种 LLM 调用各司其职——Agent(任务执行)、Reflector(评估)、Evolver(改进);
- 持久化:所有改进都写入 JSON,保证智慧跨会话延续;
- 迭代学习:每次尝试都利用上一次失败的教训;
- 有界重试:最多 3 次尝试,防止无限循环;
- 阈值判定:明确的成功标准(score >= 0.8);
- 审计轨迹:完整记录改进历史(版本、时间戳、批评);
- 低延迟优先(解耦模式):关键路径开销最小化;
- 向后兼容:传统同步模式仍然可用。
扩展点
系统预留了明确的扩展方向:
- 添加工具:扩展
AgentTools类(src/agent.py); - 自定义评估器:修改反思维度的提示词与评分标准;
- 差异化模型:各阶段使用不同模型(执行快模型、学习强模型);
- 更换存储:用数据库替代 JSON 文件持久化(
MemorySystem与EventStream均以文件为基础,可平滑替换); - 可观测性:增加日志、指标与仪表盘;
- 多轮对话:基于
TelemetryEvent的conversation_id/turn_number字段支持对话历史; - 真实工具执行:目前工具以"描述将如何使用"为主,可扩展为实际调用执行器。
更进一步的增强模块(意图检测、静默信号、智慧策展人、熔断器、约束引擎等)可参考同目录下 docs 中的对应文档,以及框架总览 README.md 的功能清单。