1. 项目定位与核心价值

AgentAssert 是一个面向自主 AI Agent 的形式化行为规约与运行时强制执行引擎。其核心思想是：开发者通过一份 YAML 契约（ContractSpec DSL）声明 Agent "必须做"与"不得做"的内容，系统在 Agent 运行时持续校验这些不变量，并在偏离时触发恢复策略或告警。

• 项目自述其为"formal behavioral specification and runtime enforcement engine for autonomous AI agents"。资料来源：README.md:7-12
• 框架的理论基础发表于 arXiv:2602.22302，覆盖六大支柱：Reliability Index、漂移动力学、组合保证、SPRT 认证等。资料来源：README.md:171-185
• v0.3.0 引入的关键项目括 Adaptive Threshold Engine、EventBus、MCP Server Monitor、PydanticAIAdapter + A2A Compliance Bridge、OTel Exporter 与 EU AI Act 报告生成。资料来源：README.md:community-context

2. 系统架构总览

AgentAssert 在 Agent 与外部世界之间插入一层"契约执行层"，其内部可分为四个相互协作的子系统：

flowchart LR
    A[YAML Contract] --> B[ContractSpec 解析器]
    B --> C[Evaluator 引擎]
    D[Agent 运行输出] --> C
    C --> E[ConstraintResult / EvaluationResult]
    E --> F[Recovery Strategies]
    E --> G[Drift & Reliability Index]
    E --> H[EventBus / OTel Exporter]
    F --> D
    H --> I[EU AI Act 报告]

• 解析器加载 contractspec: "0.1" 文档，提取 preconditions、invariants.hard、invariants.soft、recovery.strategies、drift、reliability、satisfaction 等段落。资料来源：contracts/examples/code-generation.yaml:1-30
• 评估器逐条匹配字段路径（如 output.security_practices_score），并返回 ConstraintResult 列表，统计 c_hard / c_soft 比例。资料来源：src/agentassert_abc/evaluator/models.py:1-35
• 当软不变量失败时，系统在 recovery_window 步内尝试 inject_correction、reduce_autonomy、pause_and_escalate 或 graceful_shutdown 等策略。资料来源：contracts/examples/mcp-tool-server.yaml:90-140

3. 关键组件与契约模型

3.1 ContractSpec DSL

每个契约文件遵循统一的 YAML 结构，顶级字段包括 contractspec、kind、name、version 与 metadata。示例：

README 明确指出 DSL 共提供 14 个字段操作符（如 equals、gt、gte、lt 等），并通过 satisfaction.p / delta / k 配置统计终止条件。资料来源：README.md:30-65

3.2 评估结果模型

src/agentassert_abc/evaluator/models.py 定义了不可变的 Pydantic 模型：

• ConstraintResult：name、satisfied、evidence、constraint_type（hard / soft / governance / precondition）。
• EvaluationResult：聚合 hard_results / soft_results / governance_results，并计算 c_hard、c_soft 与违规列表。

这两个模型是事件总线、漂移引擎以及外部集成（如 CrewAI guardrail）共用的数据结构。资料来源：src/agentassert_abc/evaluator/models.py:1-35

4. 集成形态与示例

AgentAssert 通过适配器层接入主流 Agent 框架，将契约结果转化为各框架原生的回调或守护栏：

• CrewAI：以 guardrail / callback 形式挂载到 Task，任务结束自动重试。资料来源：examples/06_crewai_integration.py:25-55
• PydanticAI / A2A Bridge：v0.3.0 新增，桥接 PydanticAI 与 A2A 协议。资料来源：README.md:community-context
• MCP Tool Server Monitor：对 mcp-tool-server 契约的 JSON-RPC 调用进行强制校验。资料来源：contracts/examples/mcp-tool-server.yaml:1-40

examples/ 目录提供从基础检查到组合管线的完整脚本（如 06_crewai_integration.py、07_composition_pipeline.py、08_mcp_tool_monitoring.py），覆盖企业级落地路径。资料来源：README.md:158-170

5. 文档站点与版本发布

mkdocs.yml 使用 Material 主题（含深色模式、即时导航、代码复制），并通过 mkdocstrings 自动生成 Python API 参考；站点发布至 agentassert.com/docs。资料来源：mkdocs.yml:1-40

许可证采用 AGPL-3.0，同时提供商业授权；项目隶属 Qualixar AI Agent Reliability Platform 的一部分，与 SuperLocalMemory、Qualixar OS、SLM Mesh 等七个产品形成生态。资料来源：README.md:185-220

See Also

• ContractSpec DSL 与字段操作符参考
• Evaluator 引擎与 ConstraintResult 模型
• 集成示例：CrewAI / PydanticAI / MCP
• v0.3.0 发布说明：EventBus 与 Adaptive Threshold Engine

概述与定位

ContractSpec DSL 是 AgentAssert 框架用来声明 AI Agent 行为边界的 YAML 描述语言，也是运行时强制执行的基础数据结构 ContractSpec 的序列化形式。它把"Agent 必须 / 不得做什么"翻译成可校验、可观测、可组合的形式化规约，支撑 MCP 监控、自适应阈值、EventBus 等 v0.3.0 组件（如 MCPServerMonitor 都直接消费 ContractSpec 实例）。

资料来源：src/agentassert_abc/dsl/parser.py:18-22，注释明确指出 ContractSpec DSL Parser 是"Layer 1"入口，并配合 Pydantic + 语义校验两阶段验证。

YAML 契约结构

一个最小化的契约以 contractspec: "0.1" 头声明版本与种类，下方按层级组织行为约束。典型的 kind: agent 契约包含以下区块：

• 元数据 metadata：作者、领域（domain）、创建日期、标签（tags），用于检索与归类。
• 前置条件 preconditions：执行 Agent 前必须为真的事实检查，例如 customer-session-valid、product-catalog-loaded 等。
• 不变量 invariants：分为 hard（硬约束，违反即阻断）与 soft（软约束，可触发恢复策略）；每条约束可附带 category、recovery、recovery_window。
• 恢复 recovery.strategies：软约束失败时的纠正注入（inject_correction）、暂停升级（pause_and_escalate）或优雅停机（graceful_shutdown）。
• 漂移与可靠性 drift、reliability：权重、滑动窗口与部署阈值，用于 v0.3.0 引入的自适应阈值引擎。
• 满足度 satisfaction：SPRT 参数 p、delta、k。

下表概括了 DSL 暴露的 14 个约束运算符，对应 _OPERATOR_FIELDS 中枚举的字段。

每个 check 节点都是单运算符形式：_count_operators 会确保一次只能启用一种比较语义，避免歧义。

资料来源：contracts/examples/ecommerce-product-recommendation.yaml:1-40、src/agentassert_abc/dsl/validator.py:21-39、README.md 中 ContractSpec DSL 章节。

核心数据模型

ContractSpec 是 Pydantic 化的根模型，对应 YAML 顶层；它聚合 ConstraintCheck、GovernanceConstraint、SoftConstraint 等子对象：

• ConstraintCheck：每个约束体只允许填入一个运算符字段（由 _OPERATOR_FIELDS 静态约束保证）。
• GovernanceConstraint：硬约束，违反时阻断工具调用或 Agent 行为，参见 MCPServerMonitor.check_pre_invoke 中对 hard_violations 的判定。
• SoftConstraint：软约束，触发 recovery_needed 标记，由调用方决定是否重试。

ContractSpec 还携带 preconditions、invariants、recovery、satisfaction、drift、reliability 等命名段，使解析结果可直接喂给监控器、可靠性指数计算、SPRT 引擎等下游模块。

资料来源：src/agentassert_abc/dsl/validator.py:25-50、src/agentassert_abc/monitor/mcp_monitor.py 中 MCPServerMonitor.__init__(contract: ContractSpec) 签名。

解析与校验流程

flowchart LR
    YAML[YAML 契约文件] --> P[ruamel.yaml 安全加载]
    P --> S[Pydantic 结构校验]
    S --> V[validate_contract 语义校验]
    V --> CS[ContractSpec 对象]
    CS --> M[MCPServerMonitor / Adaptive Engine]
    CS --> E[EventBus / OTel Exporter]

• 解析层：_parse_yaml 使用 ruamel.yaml.YAML(typ="safe", pure=True)，将 YAML 字符串转为 dict；若失败抛 ContractParseError。
• 结构层：由 Pydantic 把 dict 装配成 ContractSpec，类型不匹配抛 PydanticValidationError。
• 语义层：validate_contract 校验运算符一致性、引用可达性、参数范围、命名唯一性等 Pydantic 无法覆盖的规则；任何错误通过 ParseResult.errors 聚合。

这一"结构 + 语义"双层校验对应论文 arXiv:2602.22302 §3.1 / §4 的 Layer 1 规范，也是 v0.3.0 强化 MCP 工具调用合规性的基础。

常见失败模式

1. 多运算符并存：ConstraintCheck 同时设置 equals 与 gte，会触发 _count_operators > 1 的语义错误。
2. 恢复策略缺失：SoftConstraint 声明了 recovery 名称但 recovery.strategies 中找不到匹配条目，需在 customer-support.yaml 这类示例中保持命名一致。
3. 硬约束与软约束混淆：本应阻断的违规被写成 soft，会导致 MCPServerMonitor.allowed 仍为 True；务必按业务严重程度选择层级。

See Also

• README.md — 框架总览与契约示例汇总
• 论文 arXiv:2602.22302 — 形式化定义与可靠性证明
• contracts/examples/ — 12 个行业模板契约

1. 目的与定位

AgentAssert 的运行时强制执行引擎（Runtime Enforcement Engine）是 v0.3.0 版本的核心组件，负责把 YAML 形式的 ContractSpec 行为契约 转换为可在智能体（Agent）实际执行时被检查、被拦截、被恢复的运行时机制。它不是离线评测器，而是在 Agent 输出前、调用工具时、跨多个 Agent 编排时持续工作的“守门人”。资料来源：README.md

社区在 v0.3.0 发布说明中明确强调这一引擎承载了 “Formal Behavioral Contracts for AI Agents” 的全部落地能力，并配套了事件总线、阈值自适应、OTel 导出与 MCP 监控等运行时支撑。资料来源：README.md:1-40

2. 契约结构与执行输入

执行引擎消费的契约遵循 contractspec: "0.1" 这一 DSL 版本号，主体由以下四段组成：

资料来源：contracts/examples/code-generation.yaml:1-60、contracts/examples/mcp-tool-server.yaml:1-80

契约中 check 字段使用 14 种运算符（equals、not_equals、gt、gte、lt、lte 等）对 Agent 输出中的字段进行判定。资料来源：README.md:120-180

3. 强制执行流程

下图展示了引擎在一次 Agent 调用周期内的内部流转：

flowchart LR
    A[Agent 产出 output] --> B{前置条件}
    B -- 不满足 --> X1[拒绝执行 / 报错]
    B -- 满足 --> C[评估硬不变量]
    C -- 违反 --> X2[硬拦截 + 告警事件]
    C -- 通过 --> D[评估软不变量]
    D -- 违反 --> E[选择 recovery 策略]
    E --> F{超过 recovery_window?}
    F -- 否 --> G[注入纠正或降级]
    F -- 是 --> H[暂停 / 升级 / 优雅关闭]
    G --> I[继续执行]
    H --> I
    D -- 全部通过 --> I[继续执行]
    I --> J[更新漂移 / 可靠性指数]
    J --> K[EventBus / OTel 导出]

关键步骤说明：

1. 前置条件检查：例如 vector-store-connected 要求 system.vector_store_status == "available"，否则拒绝开始。资料来源：contracts/examples/rag-agent.yaml:1-40
2. 硬不变量立即阻断：no-hallucination-beyond-context、no-secrets-in-output 等条目一旦违反就中止调用，避免危险输出扩散。资料来源：contracts/examples/rag-agent.yaml:40-80、contracts/examples/code-generation.yaml:30-60
3. 软不变量 + 恢复窗口：例如 documentation_score >= 0.6 未满足时，按 recovery_window 次数执行 enrich-documentation 注入动作；超过窗口则升级。资料来源：contracts/examples/code-generation.yaml:60-120

4. 自适应阈值、事件总线与 MCP 监控

v0.3.0 在执行引擎之上扩展了三项运行时能力：

• Adaptive Threshold Engine：从校准数据中学习漂移阈值，替代了早期手写的 drift.thresholds。契约中的 drift.weights 与 window 仍可控制漂移检测的灵敏度。资料来源：README.md:1-40、contracts/examples/customer-support.yaml:120-200
• EventBus：类型化、线程安全的发布订阅总线，向外部广播 violation 与 recovery 事件，便于接入告警与审计。资料来源：README.md:1-40
• MCP Server Monitor：对 Model Context Protocol 工具服务器做契约级强制（如 tool-schema-compliance、resource-cleanup），并在响应延迟过高时执行 degrade-gracefully。资料来源：contracts/examples/mcp-tool-server.yaml:80-200

引擎还输出 Reliability Index，由 reliability.weights（compliance / drift / recovery / stress）加权汇总，并对照 deployment_threshold 决定 Agent 是否可上线。资料来源：contracts/examples/customer-support.yaml:160-260

5. 与编排框架的集成

执行引擎通过适配器嵌入到主流 Agent 框架。例如在 CrewAI 中，契约被包装为 adapter.guardrail 并作为 Task.guardrail 传入，CrewAI 在失败时按 guardrail_max_retries 次数重试；同时也支持 callback 模式进行只监测不阻断。资料来源：examples/06_crewai_integration.py:1-80

research_task = Task(
    description="Research AI agent frameworks in 2026",
    expected_output="A cited report on top 5 frameworks",
    agent=researcher,
    guardrail=adapter.guardrail,      # AgentAssert 强制执行入口
    guardrail_max_retries=3,
)

资料来源：examples/06_crewai_integration.py:20-60

6. 常见失效模式

资料来源：contracts/examples/retail-shopping-assistant.yaml:1-80、contracts/examples/ecommerce-product-recommendation.yaml:1-60

7. See Also

• ContractSpec DSL 语法参考：README.md
• 域契约目录：contracts/examples/
• 文档站导航：mkdocs.yml

概述

AgentAssert 的"认证、集成、合规与可视化"层面将契约 (ContractSpec) 从一份静态 YAML 升级为可在生产环境落地的一整套工具链：包括 SPRT 统计认证、可靠性指数计算、第三方框架适配器、合规报告生成以及 OpenTelemetry 风格的可观测性导出器。本页聚焦 v0.3.0 中已正式发布的相关能力，结合社区讨论中的高频议题（如漂移阈值漂移、跨框架迁移、欧盟 AI 法案报告）展开说明。

资料来源：README.md:1-30

认证 (Certification)

SPRT 序列概率比检验

certification/sprt.py 实现 Wald 序贯概率比检验 (Sequential Probability Ratio Test)，用于在样本量未达到传统统计显著性所需的规模前，对零假设 (H₀：违约率 ≤ p₀) 与备择假设 (H₁：违约率 ≥ p₁) 做出接受/拒绝决策。其与契约中 satisfaction 块联动：

satisfaction:
  p: 0.95      # 可接受违约率上界
  delta: 0.1   # 容忍区间
  k: 3         # 连续通过窗口

当连续 k 次执行均满足 p 阈值时，检验通过；反之触发拒绝并回滚。SPRT 显著降低了在低风险任务上等待大规模样本的延迟。

资料来源：src/agentassert_abc/certification/sprt.py:1-80、contracts/examples/code-generation.yaml:1-60

满意度与组合性认证

satisfaction.py 在窗口上累积正/负样本，并通过 Wilson 区间估计真实违约率的下界。composition.py 则把多 Agent 子契约的可靠性指数 RI 相乘，给出组合部署阈值：

RI_composite = 0.35*compliance + 0.25*drift + 0.20*recovery + 0.20*stress

资料来源：src/agentassert_abc/certification/composition.py:1-60、contracts/examples/customer-support.yaml:1-40

自适应阈值引擎

v0.3.0 引入 metrics/adaptive.py，从校准数据 (calibration data) 学习漂移阈值，替代硬编码的 warning/critical 数值。社区议题表明，固定阈值在模型版本切换时常常误报，自适应引擎通过滚动分位数估计动态收紧或放宽。

资料来源：src/agentassert_abc/metrics/adaptive.py:1-50

集成 (Integration)

适配器矩阵

下表列出官方适配器与对应入口（详见 integrations/ 目录及 README.md:1-20）：

CrewAI 集成示例

examples/06_crewai_integration.py 演示了如何在 Task 上挂载 AgentAssert guardrail：

research_task = Task(
    description="Research AI agent frameworks in 2026",
    expected_output="A cited report on top 5 frameworks",
    agent=researcher,
    output_json=ResearchOutput,
    guardrail=adapter.guardrail,      # AgentAssert 在此校验
    guardrail_max_retries=3,
)

CrewAI 在校验失败时会自动重试，AgentAssert 同时把指标写入 EventBus，便于审计。

资料来源：examples/06_crewai_integration.py:1-40

MCP 与 A2A 桥接

integrations/mcp.py 在 JSON-RPC 入口处校验工具描述、调用授权与响应 schema；pydantic_ai.py 提供 Agent-to-Agent 协议的合规桥接，确保跨供应商代理仍遵守同一份 ContractSpec。

资料来源：src/agentassert_abc/integrations/mcp.py:1-50、src/agentassert_abc/integrations/pydantic_ai.py:1-50

合规 (Compliance)

EU AI Act 报告

compliance/eu_ai_act.py 把运行时观测到的违规事件、漂移告警与恢复动作汇总为符合欧盟 AI 法案附录 IV 的报告草稿，包含：风险类别、系统描述、数据治理、人类监督机制、事件日志等条目。该报告可直接提交给审计方，避免运营方手工整理。

资料来源：src/agentassert_abc/compliance/eu_ai_act.py:1-60

契约层面的合规边界

code-generation.yaml 中的硬不变式 no-secrets-in-output 与 rag-agent.yaml 的 no-hallucination-beyond-context 都是合规级约束，违反即拒绝输出。社区关注点之一是：当合规规则与业务恢复策略冲突时，应优先触发 pause_and_escalate 而非 inject_correction。

资料来源：contracts/examples/code-generation.yaml:1-30、contracts/examples/rag-agent.yaml:1-30

可视化与可观测性 (Visualization & Observability)

OpenTelemetry 导出器

observability/otel.py 把每次契约校验封装为 OTel Span，属性包括 contract.name、invariant.name、recovery.action、drift.score。这样可以将 AgentAssert 与 Grafana/Tempo/Jaeger 等现成的 APM 栈直接对接，无需自建仪表盘。

flowchart LR
    A[Agent 调用] --> B[Adapter 拦截]
    B --> C{Contract 校验}
    C -->|通过| D[执行]
    C -->|违反| E[Recovery 策略]
    D --> F[OTel Span: PASS]
    E --> G[OTel Span: VIOLATION]
    F --> H[Grafana / Tempo]
    G --> H

资料来源：src/agentassert_abc/observability/otel.py:1-40

EventBus 与运行时仪表盘

v0.3.0 的 EventBus 提供类型化、线程安全的发布/订阅通道，事件涵盖 violation、recovery、drift、certification decision。下游消费者可以基于 EventBus 自建实时仪表盘（例如 Streamlit 或 Jupyter widget），把可靠性指数 θ 与漂移曲线叠加展示。

资料来源：examples/03_drift_detection.py:1-30

常见失败模式

1. SPRT 永不收敛：当违约率恰好在 H₀/H₁ 边界附近时，SPRT 可能持续追加样本。建议设置最大样本上限并切换回固定样本量检验。
2. 自适应阈值过松：adaptive.py 在冷启动期使用历史均值，若校准数据量不足 (<100)，阈值可能偏离真实风险。
3. CrewAI 重试风暴：guardrail_max_retries 设置过高时，会放大下游 LLM 调用成本；建议结合 recovery_window 做退避。
4. OTel 属性爆炸：把每条 invariant 都写入 Span 会导致 cardinality 过高，应在导出器侧做聚合或采样。

资料来源：src/agentassert_abc/certification/sprt.py:1-30、src/agentassert_abc/metrics/adaptive.py:1-30

See Also

• ContractSpec DSL 与 YAML 示例
• 可靠性指数与漂移动力学
• arXiv 论文：AgentAssert 形式化框架

Pitfall Log / 踩坑日志

项目：qualixar/agentassert-abc

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:1204053098 | https://github.com/qualixar/agentassert-abc | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:1204053098 | https://github.com/qualixar/agentassert-abc | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:1204053098 | https://github.com/qualixar/agentassert-abc | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:1204053098 | https://github.com/qualixar/agentassert-abc | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:1204053098 | https://github.com/qualixar/agentassert-abc | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:1204053098 | https://github.com/qualixar/agentassert-abc | release_recency=unknown