Agent Governance Toolkit 自进化 Agent 框架实战:从 Doer/Observer 解耦架构到多模态输入输出与自动化治理

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

Agent Governance Toolkit 自进化 Agent 框架实战:从 Doer/Observer 解耦架构到多模态输入输出与自动化治理

本文是 Agent Governance Toolkit 仓库中 agent-governance-python/agent-os/examples/self-evaluating 示例的完整技术指南。该示例实现了一个生产可用的"自进化 Agent 框架",覆盖多态输出(Polymorphic Output)、通用信号总线(Universal Signal Bus)、Agent 经纪层、确定性编排、约束工程(逻辑防火墙)、评估工程(新 TDD)、幽灵模式(Ghost Mode)、意图检测、静默信号、自动熔断器等 17+ 个核心模块。读完本文,你将掌握如何在 DoerAgent/ObserverAgent 解耦架构下搭建"执行快、学习离线"的自进化系统,并为每个模块找到可直接运行的示例与源码级实现依据。

一、框架定位:从"单一文本对话"到"自我改进的 Agent 操作系统"

self-evaluating 是 Agent Governance Toolkit 中一个独立、完整的 Python 示例框架(位于 agent-governance-python/agent-os/examples/self-evaluating),其核心目标可以用一句话概括:构建能根据执行反馈自动改写自身系统指令(System Instructions)的 AI Agent。

传统 Agent 的边界是"固定 Prompt + 每次手动调优";而这个框架把 反射(Reflect)与进化(Evolve) 变成了运行时的一等公民:Agent 执行任务 → 独立 LLM 评估器打分 → 低于阈值时由"进化模型"重写系统指令 → 用新指令重试,直到通过。同时,框架将这一闭环拆分为 Doer(执行者) 与 Observer(观察者) 两套进程,保证在线执行的低延迟与离线学习的深度可以兼得。

从目录结构(见 README.md)可以看出它的模块化程度:

self-evaluating/
├── src/                    # 核心框架模块(17+ 个)
│   ├── agent.py            # DoerAgent / SelfEvolvingAgent 主实现
│   ├── observer.py         # ObserverAgent 异步学习
│   ├── telemetry.py        # 事件流(EventStream)与遥测
│   ├── polymorphic_output.py      # 自适应渲染(多态输出)
│   ├── universal_signal_bus.py    # 全渠道信号归一化
│   ├── agent_brokerage.py         # Agent 经纪层(API 经济)
│   ├── agent_metadata.py          # OpenAgent Definition(OAD)
│   ├── orchestrator.py            # 确定性编排状态机
│   ├── constraint_engine.py       # 逻辑防火墙
│   ├── evaluation_engineering.py  # 评估工程(新 TDD)
│   ├── ghost_mode.py              # 幽灵模式(被动观察)
│   ├── intent_detection.py        # 意图检测
│   ├── circuit_breaker.py         # 自动熔断器
│   ├── prioritization.py          # 三层上下文优先级框架
│   ├── model_upgrade.py           # 升级清理策略
│   ├── wisdom_curator.py          # 智慧策展人(人在环)
│   └── generative_ui_engine.py    # 生成式 UI 引擎
├── examples/               # 21 个可运行示例
├── tests/                  # 18 个测试套件
├── docs/                   # 27 份特性文档
├── requirements.txt        # 仅两个依赖
└── setup.py                # 可 pip install -e . 安装

二、快速开始:两条安装路径与三种运行方式

2.1 依赖安装

该框架的第三方依赖极轻(见 requirements.txt):

openai>=1.0.0
python-dotenv>=1.2.2

提供两种安装方式:

方式一:以包形式安装(推荐)

# 克隆仓库后进入示例目录
pip install -e .

# 配置环境变量
cp .env.example .env
# 编辑 .env,填入 OPENAI_API_KEY

setup.py(见 setup.py)声明了包名 self-evolving-agent、版本 3.1.0、Python 要求 >=3.8,并注册了控制台入口 self-evolving-agent=src.agent:main。

方式二:仅安装依赖

pip install -r requirements.txt
cp .env.example .env   # 编辑 .env 添加 OPENAI_API_KEY

2.2 三分钟跑通

# 基础测试(无需 API Key,可直接运行)
python tests/test_agent.py

# 简单示例(需要 API Key)
python examples/example.py

# 全栈集成示例(Universal Signal Bus + DoerAgent + 多态输出 + 生成式 UI + 遥测)
python examples/sample_full_stack_agent.py

# 生产监控场景示例(幽灵模式 + 日志流摄入 + 置信度告警 + 仪表盘组件)
python examples/sample_monitoring_agent.py

初学建议先阅读 docs/GETTING_STARTED.md 入门指南;每项特性的详细设计文档见 docs 目录。

三、架构核心:执行与学习的解耦(Doer/Observer 模式)

3.1 Decoupled Mode 五大组件

框架推荐的生产架构是"解耦模式",其组件定义在 agent.py 与 observer.py 中:

  1. DoerAgent(执行者):同步执行任务的 Agent。
    • 以只读方式使用智慧数据库(Wisdom Database);
    • 执行期间不进行反射或学习,保证低延迟;
    • 执行后向事件流(EventStream)发射遥测事件;
    • 可选启用意图检测、熔断器、约束引擎、OAD 元数据(enable_* 开关全部默认可配置,见 DoerAgent.__init__)。
  2. ObserverAgent(观察者):异步离线学习的 Agent。
    • 离线消费遥测事件流;
    • 分析执行轨迹(analyze_trace),执行反射(reflect)与进化(evolve);
    • 演进智慧数据库(Wisdom Database);
    • 可选用更强/更贵的模型做学习(REFLECTION_MODEL / EVOLUTION_MODEL)。
  3. EventStream(事件流):追加式事件日志(JSONL 格式)。
    • 存储 task_start、task_complete、signal_* 等执行轨迹;
    • 支持批量处理与基于时间戳的断点续传(read_unprocessed(last_processed_timestamp)),实现细节见 telemetry.py。
  4. MemorySystem / Wisdom Database(智慧数据库):JSON 持久化知识库。
    • 结构为 {"version": N, "instructions": "...", "improvements": [...]};
    • update_instructions() 每次进化都会递增版本号并记录时间戳、critique(以及用于升级清理的 query/response)。
  5. AgentTools(工具集):calculate()(基于 ast 的安全数学表达式求值,只允许 + - * / ** 负号 等白名单算子)、get_current_time()、string_length()。

提示:框架兼容旧的同步模式——SelfEvolvingAgent(在 agent.py 中作为向后兼容保留),其闭环为 act() → reflect() → evolve() → run()。

3.2 解耦架构的七项收益

  1. 低运行时延迟:Doer 不需要等待学习过程;
  2. 持续学习:Observer 随事件积累不断沉淀智慧;
  3. 可扩展性:Observer 可批量处理事件;
  4. 模型灵活性:学习可使用不同/更强模型;
  5. 异步处理:学习与执行完全分离;
  6. 资源效率:学习进程可独立调度(如低峰期运行);
  7. 上下文优先级:关键信息(安全、用户偏好)在提示词中高可见性。

运行 python examples/example_decoupled.py 可看到"DoerAgent 快速执行 + ObserverAgent 离线学习"的完整演示;架构细节另见 docs/ARCHITECTURE.md 与 docs/ARCHITECTURE_DECOUPLED.md。

四、输入侧:通用信号总线与意图检测

4.1 Universal Signal Bus(全渠道输入归一化)

核心思想:"Agent 的入口不是 UI 组件,而是 Signal Normalizer(信号归一器);Agent 是输入无关(Input Agnostic)的。" 实现位于 universal_signal_bus.py,支持 8 种信号类型(SignalType):文本、文件变更、日志流、音频流、API 事件、DOM 事件、点击流、系统错误。

内置四种归一器,各自实现 SignalNormalizer 协议(normalize() + validate()):

  • TextSignalNormalizer:向后兼容的文本查询;
  • FileChangeSignalNormalizer:来自 IDE 文件监听的被动输入——自动提取意图(file_creation/code_modification/test_modification 等),对 config/security/auth 关键文件给出 high/0.8 紧急度;
  • LogStreamSignalNormalizer:系统日志输入——500 错误映射为 server_error_500 意图与 critical/0.9 紧急度,CRITICAL/FATAL 为 0.95;
  • AudioStreamSignalNormalizer:会议/语音输入——从转写文本识别 help_request、urgent_request 等意图。

UniversalSignalBus.ingest() 是唯一入口:未指定类型时调用 _detect_signal_type() 按字段启发式自动识别(file_path+change_type → 文件变更;level/error_code → 日志;transcript → 音频;text/query → 文本),全部信号统一归一化为标准 ContextObject。

手动用法示例:

from universal_signal_bus import (
    UniversalSignalBus,
    create_signal_from_text,
    create_signal_from_file_change,
    create_signal_from_log,
    create_signal_from_audio
)

bus = UniversalSignalBus()

text_context = bus.ingest(create_signal_from_text("What is 10 + 20?"))
file_context = bus.ingest(create_signal_from_file_change(
    file_path="/workspace/auth/security.py",
    change_type="modified",
    content_before="password = 'admin'",
    content_after="hashed = bcrypt.hashpw(...)",
    language="python"
))
log_context = bus.ingest(create_signal_from_log(
    level="ERROR", message="Database connection pool exhausted",
    error_code="500", service="user-api"
))
audio_context = bus.ingest(create_signal_from_audio(
    transcript="We're seeing critical performance issues", speaker_id="john_doe"
))

# 全部归一化为标准 ContextObject
print(f"Intent: {log_context.intent}")        # → "server_error_500"
print(f"Priority: {log_context.priority}")    # → "critical"
print(f"Urgency: {log_context.urgency_score}") # → 0.9

与 DoerAgent 集成时,只需一行 context = bus.ingest(raw_signal) 即可让同一 Agent 处理任何输入源:

from agent import DoerAgent
from universal_signal_bus import UniversalSignalBus

bus = UniversalSignalBus()
agent = DoerAgent()

def process_signal(raw_signal):
    context = bus.ingest(raw_signal)
    return agent.run(query=context.query, user_id=context.user_id)

process_signal({"text": "Calculate 10 + 20"})
process_signal({"file_path": "/app.py", "change_type": "modified"})
process_signal({"level": "ERROR", "message": "Failed"})
process_signal({"transcript": "Help me debug this"})

运行 python examples/example_universal_signal_bus.py 可看到 8 种演示场景;详细文档见 docs/UNIVERSAL_SIGNAL_BUS.md。

4.2 Intent Detection(意图感知评估)

同一个指标不可能同时衡量"修 Bug"和"头脑风暴"。意图检测在第一轮对话即判定会话类型(实现见 intent_detection.py,由 DoerAgent 在 turn_number == 1 时调用):

  • Troubleshooting(排障):成功 = 快速解决(≤3 轮);超过 3 轮 = 用户被困住了,是失败;
  • Brainstorming(头脑风暴):成功 = 深度探索(≥5 轮);过浅(<5 轮)= 失败。

关键洞察:"Engagement is often Failure——一个 20 轮的密码重置流程说明用户被困住了,而不是投入。"Observer 侧通过 evaluate_conversation_by_intent() 对完整会话按意图专用指标评估,详见 observer.py(IntentMetrics.evaluate_troubleshooting / evaluate_brainstorming)。

from agent import DoerAgent
import uuid

doer = DoerAgent()
conversation_id = str(uuid.uuid4())

doer.run(query="How do I reset my password?", conversation_id=conversation_id, turn_number=1)
doer.run(query="Thanks, that worked!", conversation_id=conversation_id, turn_number=2)

from observer import ObserverAgent
observer = ObserverAgent()
observer.process_events()  # 按意图专用指标评估

演示:python examples/example_intent_detection.py;文档见 docs/INTENT_DETECTION.md。

五、输出侧:多态输出与生成式 UI 引擎

核心思想:"如果输入可以是任何东西,输出就必须是任何东西。Agent 生成数据,接口层生成视图——这就是 Just-in-Time UI。" 实现位于 polymorphic_output.py 与 generative_ui_engine.py。

OutputModalityDetector.detect_modality() 依据输入上下文 + 数据类型 + 信号类型 + 紧急度的 8 条规则确定输出形态(OutputModality 枚举含 12 种):IDE 上下文 → 幽灵文本/内联错误;监控上下文 → 仪表盘组件/图表;紧急度 ≥0.8 → 通知;表格数据 → 表格;时序数据 → 图表;代码 → 代码片段;结构化 → 卡片;列表 → 列表;默认 → 文本。

from polymorphic_output import (
    PolymorphicOutputEngine, InputContext,
    create_ghost_text_response, create_dashboard_widget_response,
    create_chart_response, create_table_response
)
from generative_ui_engine import GenerativeUIEngine

output_engine = PolymorphicOutputEngine()
ui_engine = GenerativeUIEngine()

# 场景 1:遥测流 → 仪表盘组件
telemetry_data = {"metric_name": "API Latency", "metric_value": "2000ms",
                  "trend": "up", "alert_level": "critical"}
poly_response = output_engine.generate_response(
    data=telemetry_data, input_context=InputContext.MONITORING,
    input_signal_type="log_stream", urgency=0.9)
ui_component = ui_engine.render(poly_response)
print(f"Modality: {poly_response.modality}")   # → dashboard_widget
print(f"Component: {ui_component.component_type}")  # → DashboardWidget

# 场景 2:IDE 上下文 → 幽灵文本
ghost_response = create_ghost_text_response(
    suggestion="def calculate_total(items: List[float]) -> float:\n    return sum(items)",
    cursor_position={"line": 42, "column": 16})
ui_component = ui_engine.render(ghost_response)   # 部署到 IDE: ide.show_ghost_text(...)

# 场景 3:SQL 结果 → 交互式表格
table_response = create_table_response(
    rows=[{"id": 1, "name": "Alice", "email": "alice@example.com"},
          {"id": 2, "name": "Bob", "email": "bob@example.com"}],
    title="Users", sortable=True, filterable=True)

# 场景 4:时间序列 → 折线图
chart_response = create_chart_response(
    chart_type="line",
    data_points=[{"timestamp": "00:00", "value": 100},
                 {"timestamp": "01:00", "value": 120},
                 {"timestamp": "02:00", "value": 150}],
    title="Request Rate", x_axis_label="Time", y_axis_label="Requests/min")

将现有 Agent 包装为"多态"版本:

from agent import DoerAgent
from polymorphic_output import PolymorphicOutputEngine, InputContext
from generative_ui_engine import GenerativeUIEngine

class PolymorphicDoerAgent(DoerAgent):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.poly_engine = PolymorphicOutputEngine()
        self.ui_engine = GenerativeUIEngine()

    def run_polymorphic(self, query, input_context, **kwargs):
        result = self.run(query, **kwargs)
        poly_response = self.poly_engine.generate_response(
            data=result['response'], input_context=input_context)
        ui_component = self.ui_engine.render(poly_response)
        return {**result, 'polymorphic_response': poly_response, 'ui_component': ui_component}

agent = PolymorphicDoerAgent()
print(agent.run_polymorphic("Complete: def calculate_", InputContext.IDE)['polymorphic_response'].modality)        # → ghost_text
print(agent.run_polymorphic("Show current latency", InputContext.MONITORING)['polymorphic_response'].modality)   # → dashboard_widget

运行 python examples/example_polymorphic_output.py 查看 8 个演示场景(数据→仪表盘、代码→幽灵文本、分析→表格、监控→图表、告警→Toast、自动模态检测、React 代码生成等);文档见 docs/POLYMORPHIC_OUTPUT.md。

六、安全层:约束工程(逻辑防火墙)与 Wisdom Curator

6.1 Constraint Engineering:大脑与手之间的确定性防火墙

架构三要素(见 constraint_engine.py):

  1. Brain(LLM):高温度生成创意计划;
  2. Firewall(约束引擎):确定性 Python 校验层;
  3. Hand(执行器):仅当防火墙批准后才执行。

原则:"人类建墙,AI 在墙内玩耍(The Human builds the walls; the AI plays inside them)。" 内置五条规则(ConstraintRule 子类):

规则 拦截内容 严重级别
SQLInjectionRule DROP TABLE、DELETE ... WHERE 1=1、命令拼接注入、SQL 块注释 CRITICAL
FileOperationRule rm -rf /、del /s /q *、format C:、dd ... of=/dev/;保护 /etc、/sys、/boot、/bin、C:\Windows 等路径 CRITICAL / HIGH
CostLimitRule 单动作成本超限(默认 $0.05,超过 80% 触发 LOW 预警) HIGH / LOW
EmailDomainRule 非白名单收件域名 MEDIUM
RateLimitRule 每分钟动作频率超限(默认 10 次/分钟) MEDIUM

只有 CRITICAL 与 HIGH 违规才会阻断执行(ConstraintResult.get_blocking_violations())。

from constraint_engine import create_default_engine

engine = create_default_engine(max_cost=0.05, allowed_domains=["example.com", "company.com"])

ai_plan = {"action_type": "sql_query", "action_data": {"query": "DROP TABLE users"}}
result = engine.validate_plan(ai_plan, verbose=True)

if result.approved:
    execute_action(ai_plan)
else:
    for violation in result.get_blocking_violations():
        print(f"  - {violation.message}")   # Dangerous SQL operation detected

集成到 DoerAgent 后,每次执行前可调用 doer.validate_action_plan(plan, verbose=True) 预检;同时 intercept_and_validate() 支持"校验通过则自动执行"的拦截模式。演示:python examples/example_constraint_engineering.py;文档见 docs/CONSTRAINT_ENGINEERING.md。

6.2 Wisdom Curator:人在环的战略把关

将人类角色从"编辑(修语法)"升级为"策展人(审批知识)"(实现见 wisdom_curator.py)。三种审查类型:

  1. Design Check:验证实现是否对齐架构提案(校验"是否做对了",而非语法);
  2. Strategic Sample:随机抽样(如 10000 条中抽 50 条)做质量/风格检查,sample_rate=0.005 即 0.5%;
  3. Policy Review:人类审批可阻止有害智慧更新(如"忽略所有错误"),自动检测安全/隐私/质量违规。
from wisdom_curator import WisdomCurator, DesignProposal, ReviewType

curator = WisdomCurator(sample_rate=0.005)

# 1. 设计对齐检查
proposal = DesignProposal(proposal_id="auth_v1", title="User Authentication System",
                          description="Implement JWT-based auth",
                          key_requirements=["Use JWT tokens", "Add rate limiting"])
curator.register_design_proposal(proposal)
review = curator.verify_design_alignment(proposal_id="auth_v1",
    implementation_description="Implemented JWT with bcrypt...")

# 2. 战略抽样
if curator.should_sample_interaction():
    curator.create_strategic_sample(query="User query", agent_response="Agent response")

# 3. 策略审查(命中违规则阻断自动更新)
if curator.requires_policy_review(proposed_wisdom, critique):
    curator.create_policy_review(proposed_wisdom=proposed_wisdom,
                                 current_wisdom=current_wisdom, critique=critique)

# 审批管理
pending = curator.get_pending_reviews(ReviewType.POLICY_REVIEW)
curator.approve_review(review_id, "Safe to apply")
curator.reject_review(review_id, "Harmful pattern")

# 与 Observer 自动集成
from observer import ObserverAgent
observer = ObserverAgent(enable_wisdom_curator=True)
observer.process_events()   # 策略审查自动发生

在 observer.py 的 learn_from_analysis() 中可以看到集成逻辑:当进化出的新指令命中策略违规时,不会自动写入智慧库,而是创建 policy_review 待人工审批(<a href="https://link.gitcode.com/i/6d04a08c426512a0c23aaf7661002e12" target="_blank">WISDOM CURATOR] Wisdom update BLOCKED pending human approval)。演示:python examples/example_wisdom_curator.py;文档见 [docs/WISDOM_CURATOR.md。

七、质量层:评估工程(新 TDD)

核心思想:"如果答案正确但态度粗鲁,打 5/10;如果答案错误但态度礼貌,打 0/10。 质量是多维度的。未来的'源代码'就是约束 AI 的评估套件。" 实现见 evaluation_engineering.py。

三步走(Eval-DD:Evaluation-Driven Development——先写"考卷",让 AI 迭代直到及格):

  1. Golden Dataset(黄金数据集):用带期望输出的测试用例定义"好"——这是工程师在概率世界写的"代码"(EvaluationDataset.add_case(),支持 tags 与 difficulty 分级);
  2. Scoring Rubric(评分量规):多维评估——正确性 70% + 清晰度 30%,set_pass_threshold(0.9) 设置及格线(ScoringCriteria 支持注入自定义 evaluator;ScoreType 枚举含 correctness/tone/completeness/clarity/safety/efficiency/custom);
  3. EvaluationRunner(评估运行器):对 AI 函数逐用例执行并打分汇总,相当于"AI 界的 pytest"。
from evaluation_engineering import EvaluationDataset, ScoringRubric, EvaluationRunner

# 1. 写黄金数据集(这就是你的"代码")
dataset = EvaluationDataset(name="Date Parsing", description="50 tricky date strings")
dataset.add_case(id="parse_001", input="Parse: Jan 15, 2024",
                 expected_output="2024-01-15", tags=["readable"])

# 2. 写评分量规
rubric = ScoringRubric("Date Parser", "Correctness + Clarity")
rubric.add_criteria(dimension="correctness", weight=0.7,
                    description="Is the date correct?", evaluator=correctness_evaluator)
rubric.add_criteria(dimension="tone", weight=0.3,
                    description="Is response clear?", evaluator=tone_evaluator)
rubric.set_pass_threshold(0.9)

# 3. 运行评估
runner = EvaluationRunner(dataset, rubric, my_ai_function)
results = runner.run(verbose=True)

if results['overall_passed']:
    print("AI meets requirements!")
else:
    for case in runner.get_failed_cases():
        print(f"Failed: {case.case_id}")

模块还附带 4 个可复用评估器:exact_match_evaluator、contains_keywords_evaluator、length_check_evaluator、no_harmful_content_evaluator。演示:python examples/example_evaluation_engineering.py;文档见 docs/EVALUATION_ENGINEERING.md。

八、编排与经纪:确定性编排器与 Agent 市场

8.1 Orchestration Layer:确定性状态机管概率工人

关键洞察:"大脑(AI 工人)是概率性的,骨架(编排器)是确定性的。" 实现见 orchestrator.py:

  • Hub & Spoke 模式:工人之间不直接通信,全部通过 Hub(编排器)中转;
  • Transformer Middleware:管理概率工人之间的数据流转;
  • 预置流水线:如 Product Manager → Coder → Reviewer 的建站流水线(create_build_website_workflow());
  • 失败处理:预定义回退路径。
from orchestrator import Orchestrator, WorkerDefinition, WorkerType, create_build_website_workflow

orchestrator = Orchestrator()
orchestrator.register_worker(WorkerDefinition(
    worker_type=WorkerType.CODER, name="AI Coder",
    description="Implements code based on specs",
    executor=coder_function, input_transformer=transform_input))
orchestrator.register_workflow(create_build_website_workflow())

result = orchestrator.execute_workflow(workflow_name="build_website",
                                       goal="Build a portfolio website", verbose=True)
print(f"Final State: {result.state}")          # 确定性状态机推进
print(f"Steps Executed: {len(result.history)}")

DoerAgent 可直接作为编排器中的 AI 工人(executor=ai_worker,内部 doer.run(input_data))。演示:python examples/example_orchestration.py(mock 工人)与 python examples/example_orchestration_ai.py(真实 AI,需 API Key);文档见 docs/ORCHESTRATION.md。

8.2 Agent Brokerage:按次计费的 API 经济

实现见 agent_brokerage.py。核心概念:Agent 市场(注册/发现/竞价)+ 微支付(按次付费而非订阅)+ 动态选择(orchestrator 按约束选最优 Agent)。

from agent_brokerage import AgentMarketplace, AgentBroker, AgentListing, AgentPricing, PricingModel, create_sample_agents

marketplace = AgentMarketplace()
for agent in create_sample_agents():
    marketplace.register_agent(agent)

broker = AgentBroker(marketplace)
result = broker.execute_task(
    task="Extract text from invoice.pdf",
    selection_strategy="best_value",        # 或 "cheapest" / "fastest" / "most_reliable"
    user_constraints={"max_budget": 0.05, "max_latency_ms": 2000},
    verbose=True)
print(f"Agent Selected: {result['agent_name']}")
print(f"Actual Cost: ${result['actual_cost']:.4f}")

report = broker.get_usage_report()
print(f"Total Spent: ${report['total_spent']:.4f}")

注册自有 Agent 只需声明定价与能力清单;也可以把 DoerAgent 包装成市场 Agent(AgentListing(agent_id="doer_agent", capabilities=<a href="https://link.gitcode.com/i/d536ffdc3d4fd4f262b9c90d40958db1" target="_blank">...], executor=doer_executor, ...))。关键洞察:"旧世界:每月订阅 $20;新世界:为 10 秒付 $0.01。未来是专业 Agent 按效用出售的 API 经济。"演示:python examples/example_agent_brokerage.py;文档见 [docs/AGENT_BROKERAGE.md。

8.3 OpenAgent Definition(OAD):AI 的"USB 端口"

实现见 agent_metadata.py。OAD 是 Agent 的标准接口定义语言(类比 OpenAPI/Swagger),包含:Capabilities(能做什么)、Constraints(不做什么)、IO Contract(标准输入输出契约)、Trust Score(成功率/延迟/执行次数等动态指标)、Agent Discovery(市场发现)、Agent Composition(兼容性校验与流水线构建)。

from agent_metadata import AgentMetadata, AgentMetadataManager

metadata = AgentMetadata(agent_id="github-coder", name="GitHub Coder Agent",
                         version="2.3.1", description="Specialized agent for GitHub code operations")
metadata.add_capability(name="python_code_generation",
                        description="Can generate Python 3.9+ code", tags=["python", "code-generation"])
metadata.add_constraint(type="access", description="No internet access outside GitHub API", severity="high")
metadata.set_io_contract(input_schema={"type": "object", "properties": {...}},
                         output_schema={"type": "object", "properties": {...}})
metadata.set_trust_score(success_rate=0.93, avg_latency_ms=2400.0, total_executions=1547)

manager = AgentMetadataManager("agent_manifest.json")
manager.save_manifest(metadata)
manager.publish_manifest()

DoerAgent 开启 enable_metadata=True 后会自动维护清单,每次执行后更新信任分(见 DoerAgent.run() 中 metadata.update_trust_score(success=..., latency_ms=...)),并可 doer.get_metadata_manifest() / doer.publish_manifest()。演示:python examples/example_agent_metadata.py;文档见 docs/OPENAGENT_DEFINITION.md。

九、反馈与观察:静默信号与幽灵模式

9.1 Silent Signals:从用户"行为"而非"言语"学习

三种隐式反馈信号(实现在 agent.py 的 emit_*_signal 系列方法,Observer 侧由 analyze_signal() 解析,见 observer.py):

信号 含义 学习优先级
Undo 用户撤销 Agent 行为(Ctrl+Z/回滚),最响亮的"差评" critical(score 0.0)
Abandonment 用户中途停止响应,工作流丢失 high(score 0.3)
Acceptance 用户无追问直接进入下一任务 positive(score 1.0,强化用)
from agent import DoerAgent
doer = DoerAgent()

doer.emit_undo_signal(query="Write code to delete files",
                      agent_response="rm -rf /*", undo_action="Ctrl+Z in editor", user_id="user123")
doer.emit_abandonment_signal(query="Help me debug", agent_response="Check your code",
                             interaction_count=3, user_id="user456")
doer.emit_acceptance_signal(query="Calculate 10 + 20", agent_response="Result is 30",
                            next_task="Calculate 20 + 30", user_id="user789")

所有信号以 signal_* 事件类型进入 JSONL 事件流,Observer 离线按优先级学习。演示:python examples/example_silent_signals.py;文档见 docs/SILENT_SIGNALS.md。

9.2 Ghost Mode:不可见,直到不可或缺

"未来接口不是目的地(网站),而是守护进程(后台进程)。" 实现见 ghost_mode.py:后台守护线程静默消费信号流 → 只做 Dry-Run 分析(不采取行动)→ 仅当置信度超过阈值才浮出(默认 confidence_threshold=0.7)→ 通过 ContextShadow 在本地学习用户工作流模式(Behavior Model)。

from ghost_mode import GhostModeObserver, ContextShadow, BehaviorPattern, ObservationResult

def on_high_confidence(observation: ObservationResult):
    print(f"🔔 {observation.observation}")
    if observation.recommendation:
        print(f"💡 {observation.recommendation}")

observer = GhostModeObserver(confidence_threshold=0.7, surfacing_callback=on_high_confidence)
observer.start_observing(poll_interval=1.0)          # 后台线程运行
observer.observe_signal({"type": "file_change", "data": {"file_path": "/config/secrets.yaml", "change_type": "modified"}})
# → 高置信度浮出:"Security-sensitive file modified"
observer.stop_observing()
print(observer.get_stats())

Context Shadow 可学习并查询用户工作流(shadow.learn_pattern(BehaviorPattern(...)) / shadow.query_patterns(trigger=..., min_confidence=0.5)),当用户再次执行相同工作流时,Ghost Mode 识别触发点并主动建议下一步("Suggest next step: review_files")。演示:python examples/example_ghost_mode.py;文档见 docs/GHOST_MODE.md。

十、生产化:优先级框架、升级清理与自动熔断器

10.1 Prioritization Framework:三层上下文排序

实现见 prioritization.py,是"类 Graph RAG"的三层上下文排名系统,位于数据库与 Agent 之间:

  1. Safety Layer(最高优先级):"最近是否在完全相同的任务上失败过?"——以高紧急度注入纠正信息,防止重蹈覆辙,默认 7 天时间窗(learn_from_failure() 记录安全纠正);
  2. Personalization Layer(中优先级):"该用户是否有偏好约束?"(如"总是输出 JSON"),从反馈中学习(learn_user_preference()),按优先级排序;
  3. Global Wisdom Layer(低优先级):通用最佳实践(基础系统指令)。
python examples/example_prioritization.py   # 运行优先级演示
python tests/test_prioritization.py         # 测试优先级框架

文档见 docs/PRIORITIZATION_FRAMEWORK.md。

10.2 Upgrade Purge Strategy:智慧库的主动生命周期管理

升级基座模型(如 GPT-3.5 → GPT-4)后,很多旧教训会被新模型原生解决,继续保留只会拖累提示词。实现见 model_upgrade.py,流程为:Audit(用新模型复测旧失败场景)→ Identify(标记新模型已原生解决的教训)→ Purge(自动删除冗余教训)→ Result(更精简、更专业的智慧库)。把智慧当作高性能缓存来管理。

from model_upgrade import ModelUpgradeManager

manager = ModelUpgradeManager()
report = manager.perform_upgrade(new_model="gpt-4o",
                                 baseline_instructions="Your baseline system prompt...",
                                 score_threshold=0.8, auto_purge=True)
python examples/example_upgrade_purge.py   # 升级清理演示
python tests/test_model_upgrade.py         # 升级功能测试

文档见 docs/UPGRADE_PURGE.md。

10.3 Automated Circuit Breaker:确定性指标驱动的自动发布管理

实现见 circuit_breaker.py,替代"旧世界"手动 A/B 测试:Probe(探针):1% → 5% → 20% → 100% 渐进放量(RolloutPhase 枚举);Watchdog(看门狗):实时监控任务完成率与延迟;Auto-Scale:指标达标自动推进;Auto-Rollback:指标恶化立即回滚。状态机三态:CLOSED(正常)→ MONITORING(收集数据)→ OPEN(熔断,流量全回旧版)。

在 DoerAgent 中启用:

from agent import DoerAgent
doer = DoerAgent(enable_circuit_breaker=True, circuit_breaker_config_file="cb_config.json")
result = doer.run(query="What is 10 + 20?", user_id="user123")
print(f"Version: {result['version_used']}")      # old / new
print(f"Latency: {result['latency_ms']:.0f}ms")

配置项(CircuitBreakerConfig 数据类,源码默认值):

from circuit_breaker import CircuitBreakerConfig
config = CircuitBreakerConfig(
    min_task_completion_rate=0.85,   # 任务完成率不得低于 85%
    max_latency_ms=2000.0,           # 延迟不得超过 2000ms
    min_samples_per_phase=10,        # 每阶段最少样本数(不足则等待)
    monitoring_window_minutes=5,     # 指标计算时间窗
    # 另有:initial_phase=PROBE、advancement_threshold=0.95、rollback_threshold=0.80
)

流量路由采用确定性哈希(hash(request_id) % 100 < new_pct * 100),同一用户在同一阶段内路由一致;熔断状态持久化到 circuit_breaker_state.json(保留最近 1000 条指标)。should_use_new_version()、record_execution()、evaluate_and_decide() 构成完整调用链,DoerAgent 以 10% 概率(CIRCUIT_BREAKER_EVAL_PROBABILITY = 0.1)触发评估。

python examples/example_circuit_breaker.py   # 熔断器演示
python tests/test_circuit_breaker.py         # 熔断器测试

文档见 docs/CIRCUIT_BREAKER.md。

十一、配置与环境变量

所有配置通过 .env 文件加载(python-dotenv,见 agent.py 顶部 load_dotenv()):

环境变量 作用 默认值
OPENAI_API_KEY OpenAI API Key(必需) —
AGENT_MODEL 执行模型 gpt-4o-mini
REFLECTION_MODEL 反射评估模型 gpt-4o-mini
EVOLUTION_MODEL 进化重写模型 gpt-4o-mini
SCORE_THRESHOLD 最低可接受分数 0.8
MAX_RETRIES 最大重试次数 3

智慧库文件 system_instructions.json 的初始结构(仓库自带版本,见 system_instructions.json):

{
  "version": 1,
  "instructions": "You are a helpful AI assistant. Your goal is to provide accurate and useful responses to user queries. You have access to tools that you can use to help answer questions. Always think step-by-step and provide clear, concise answers.",
  "improvements": []
}

进化后的形态(每次更新版本号 +1 并记录 critique 与时间戳):

{
  "version": 2,
  "instructions": "You are a helpful AI assistant...",
  "improvements": [
    {"version": 2, "timestamp": "2024-01-01T12:00:00", "critique": "Agent should explicitly mention tool usage..."}
  ]
}

十二、测试矩阵与典型运行输出

所有测试无需 API Key 即可运行(只有真正调用 LLM 的示例需要 Key)。18 个测试套件对应 17 个模块:

python tests/test_agent.py                # 核心 Agent 功能
python tests/test_telemetry.py            # 遥测系统
python tests/test_polymorphic_output.py   # 多态输出
python tests/test_universal_signal_bus.py # 通用信号总线
python tests/test_agent_brokerage.py      # Agent 经纪层
python tests/test_agent_metadata.py       # OAD 元数据
python tests/test_orchestration.py        # 编排层
python tests/test_constraint_engineering.py  # 约束工程
python tests/test_evaluation_engineering.py  # 评估工程
python tests/test_decoupled.py            # 解耦架构
python tests/test_wisdom_curator.py       # 智慧策展人
python tests/test_prioritization.py       # 优先级框架
python tests/test_model_upgrade.py        # 升级清理
python tests/test_silent_signals.py       # 静默信号
python tests/test_intent_detection.py     # 意图检测
python tests/test_circuit_breaker.py      # 熔断器
python tests/test_ghost_mode.py           # 幽灵模式

SelfEvolvingAgent.run() 的典型迭代输出(同步模式):

ATTEMPT 1/3
Current Instructions Version: 1
[ACTING] Processing query...
Agent Response: To calculate 15 * 24 + 100...
[REFLECTING] Evaluating response...
Score: 0.6
Critique: The agent did not clearly identify the calculator tool...
[EVOLVING] Score 0.6 below threshold 0.8
Rewriting system instructions...

ATTEMPT 2/3
[ACTING] Processing query...
Agent Response: I will use the calculate() tool...
[REFLECTING] Evaluating response...
Score: 0.9
[SUCCESS] Score 0.9 meets threshold 0.8

可以看到:第一次尝试因"未明确识别工具"得 0.6 分,进化模型重写系统指令后,第二次尝试得分 0.9 通过——这正是"以评估套件为源代码、让 AI 迭代到及格"的自进化闭环。observer.py 的 process_events() 输出则包含三类统计:信号统计(undo/abandonment/acceptance)、意图评估统计(troubleshooting/brainstorming 的失败数)、策展人统计(策略审查 pending/approved/rejected)。

结语

self-evaluating 示例把 Agent 从"带 Prompt 的 API 调用"升级为"带反射、进化、治理与生产管控的自适应系统":输入侧有 Universal Signal Bus 与意图检测,输出侧有多态渲染与生成式 UI,中间层有确定性编排器、逻辑防火墙与评估工程,外层还有熔断器、优先级框架、智慧策展人与升级清理等生产级治理能力。无论是希望快速复刻一个"自我改进 Agent"的最小闭环,还是想研究 Agent 治理工具箱中各类治理模式的 Python 落地形态,这个目录(源码 src、示例 examples、测试 tests、文档 docs)都是一份可直接运行、逐模块对照学习的参考实现。

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