# https://github.com/qualixar/agentassert-abc 项目说明书

生成时间：2026-06-12 05:38:05 UTC

## 目录

- [概览与系统架构](#page-1)
- [ContractSpec DSL 与核心数据模型](#page-2)
- [运行时强制执行引擎](#page-3)
- [认证、集成、合规与可视化](#page-4)

<a id='page-1'></a>

## 概览与系统架构

### 相关页面

相关主题：[ContractSpec DSL 与核心数据模型](#page-2), [运行时强制执行引擎](#page-3), [认证、集成、合规与可视化](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/qualixar/agentassert-abc/blob/main/README.md)
- [mkdocs.yml](https://github.com/qualixar/agentassert-abc/blob/main/mkdocs.yml)
- [pyproject.toml](https://github.com/qualixar/agentassert-abc/blob/main/pyproject.toml)
- [contracts/examples/code-generation.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/code-generation.yaml)
- [contracts/examples/rag-agent.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/rag-agent.yaml)
- [contracts/examples/research-assistant.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/research-assistant.yaml)
- [contracts/examples/mcp-tool-server.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/mcp-tool-server.yaml)
- [contracts/examples/customer-support.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/customer-support.yaml)
- [contracts/examples/ecommerce-customer-service.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/ecommerce-customer-service.yaml)
- [examples/06_crewai_integration.py](https://github.com/qualixar/agentassert-abc/blob/main/examples/06_crewai_integration.py)
- [src/agentassert_abc/evaluator/models.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/evaluator/models.py)
</details>

# 概览与系统架构

## 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 与外部世界之间插入一层"契约执行层"，其内部可分为四个相互协作的子系统：

```mermaid
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`。示例：

| 段落 | 作用 | 示例来源 |
| --- | --- | --- |
| `preconditions` | 系统就绪检查（如 vector store、auth 上下文） | [contracts/examples/rag-agent.yaml:23-45]() |
| `invariants.hard` | 强制不变量，违反即终止 | [contracts/examples/code-generation.yaml:55-80]() |
| `invariants.soft` | 质量偏好，可触发恢复 | [contracts/examples/research-assistant.yaml:60-90]() |
| `recovery.strategies` | 命名恢复动作，含 `max_attempts` 与 `fallback` | [contracts/examples/mcp-tool-server.yaml:100-140]() |
| `drift` / `reliability` | 漂移检测与可靠性指数权重 | [contracts/examples/customer-support.yaml:130-160]() |

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]()

---

<a id='page-2'></a>

## ContractSpec DSL 与核心数据模型

### 相关页面

相关主题：[概览与系统架构](#page-1), [运行时强制执行引擎](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/agentassert_abc/models.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/models.py)
- [src/agentassert_abc/dsl/__init__.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/dsl/__init__.py)
- [src/agentassert_abc/dsl/models.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/dsl/models.py)
- [src/agentassert_abc/dsl/parser.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/dsl/parser.py)
- [src/agentassert_abc/dsl/validator.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/dsl/validator.py)
- [contracts/examples/ecommerce-product-recommendation.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/ecommerce-product-recommendation.yaml)
- [src/agentassert_abc/monitor/mcp_monitor.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/monitor/mcp_monitor.py)
- [README.md](https://github.com/qualixar/agentassert-abc/blob/main/README.md)
</details>

# ContractSpec DSL 与核心数据模型

## 概述与定位

ContractSpec DSL 是 AgentAssert 框架用来声明 AI Agent 行为边界的 YAML 描述语言，也是运行时强制执行的基础数据结构 `ContractSpec` 的序列化形式。它把"Agent 必须 / 不得做什么"翻译成可校验、可观测、可组合的形式化规约，支撑 MCP 监控、自适应阈值、EventBus 等 v0.3.0 组件（如 [MCPServerMonitor](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/monitor/mcp_monitor.py) 都直接消费 `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`](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/dsl/validator.py) 中枚举的字段。

| 类别 | 运算符 | 典型用途 |
| --- | --- | --- |
| 等值 | `equals`, `not_equals` | 布尔字段、字符串开关，如 `output.pii_detected equals false` |
| 区间 | `gt`, `gte`, `lt`, `lte`, `between` | 阈值类评分，例如 `output.tone_score gte 0.7` |
| 集合 | `in_`, `not_in`, `contains`, `not_contains` | 枚举与列表归属 |
| 模式 | `matches`, `exists` | 正则匹配、字段存在性 |
| 表达 | `expr` | 复合条件 / 跨字段表达式 |

每个 `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](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/monitor/mcp_monitor.py) 中对 `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)` 签名。

## 解析与校验流程

```mermaid
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`](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/dsl/parser.py) 使用 `ruamel.yaml.YAML(typ="safe", pure=True)`，将 YAML 字符串转为 dict；若失败抛 `ContractParseError`。
- **结构层**：由 Pydantic 把 dict 装配成 `ContractSpec`，类型不匹配抛 `PydanticValidationError`。
- **语义层**：[`validate_contract`](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/dsl/validator.py) 校验运算符一致性、引用可达性、参数范围、命名唯一性等 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`](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/customer-support.yaml) 这类示例中保持命名一致。
3. **硬约束与软约束混淆**：本应阻断的违规被写成 `soft`，会导致 `MCPServerMonitor.allowed` 仍为 True；务必按业务严重程度选择层级。

## See Also

- [README.md](https://github.com/qualixar/agentassert-abc/blob/main/README.md) — 框架总览与契约示例汇总
- 论文 [arXiv:2602.22302](https://arxiv.org/abs/2602.22302) — 形式化定义与可靠性证明
- [contracts/examples/](https://github.com/qualixar/agentassert-abc/tree/main/contracts/examples) — 12 个行业模板契约

---

<a id='page-3'></a>

## 运行时强制执行引擎

### 相关页面

相关主题：[ContractSpec DSL 与核心数据模型](#page-2), [认证、集成、合规与可视化](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/qualixar/agentassert-abc/blob/main/README.md)
- [mkdocs.yml](https://github.com/qualixar/agentassert-abc/blob/main/mkdocs.yml)
- [contracts/examples/code-generation.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/code-generation.yaml)
- [contracts/examples/rag-agent.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/rag-agent.yaml)
- [contracts/examples/research-assistant.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/research-assistant.yaml)
- [contracts/examples/mcp-tool-server.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/mcp-tool-server.yaml)
- [contracts/examples/customer-support.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/customer-support.yaml)
- [contracts/examples/ecommerce-product-recommendation.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/ecommerce-product-recommendation.yaml)
- [contracts/examples/retail-shopping-assistant.yaml](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/retail-shopping-assistant.yaml)
- [examples/06_crewai_integration.py](https://github.com/qualixar/agentassert-abc/blob/main/examples/06_crewai_integration.py)
</details>

# 运行时强制执行引擎

## 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 版本号，主体由以下四段组成：

| 段 | 作用 |
| --- | --- |
| `preconditions` | 前置条件，如向量库可用、嵌入模型已加载、传输层初始化 |
| `invariants.hard` | 硬不变量，违反即立即阻断（如 `no-secrets-in-output`、`tool-schema-compliance`） |
| `invariants.soft` | 软不变量，违反后触发 `recovery` 策略并受 `recovery_window` 限制 |
| `recovery.strategies` | 恢复动作（`inject_correction` / `reduce_autonomy` / `pause_and_escalate` / `graceful_shutdown`） |

资料来源：[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 调用周期内的内部流转：

```mermaid
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]()

```python
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. 常见失效模式

| 现象 | 根因 | 缓解方式 |
| --- | --- | --- |
| 硬不变量频繁触发阻断 | 上下文字段未传齐（`context.*`） | 补充 `preconditions` 所依赖的状态字段 |
| 软不变量反复重试 | `recovery_window` 设置过大 | 调小窗口或配置 `fallback` 升级策略 |
| 漂移告警风暴 | 阈值与 `drift.window` 不匹配 | 使用 v0.3.0 Adaptive Threshold Engine 自学习阈值 |
| OTel 导出链路断 | 未订阅 EventBus 的 violation 事件 | 注册 `EventBus.subscribe("violation", ...)` 消费者 |

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

## 7. See Also

- ContractSpec DSL 语法参考：[README.md](https://github.com/qualixar/agentassert-abc/blob/main/README.md)
- 域契约目录：[contracts/examples/](https://github.com/qualixar/agentassert-abc/tree/main/contracts/examples)
- 文档站导航：[mkdocs.yml](https://github.com/qualixar/agentassert-abc/blob/main/mkdocs.yml)

---

<a id='page-4'></a>

## 认证、集成、合规与可视化

### 相关页面

相关主题：[概览与系统架构](#page-1), [运行时强制执行引擎](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/agentassert_abc/certification/sprt.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/certification/sprt.py)
- [src/agentassert_abc/certification/satisfaction.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/certification/satisfaction.py)
- [src/agentassert_abc/certification/composition.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/certification/composition.py)
- [src/agentassert_abc/metrics/adaptive.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/metrics/adaptive.py)
- [src/agentassert_abc/integrations/langgraph.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/integrations/langgraph.py)
- [src/agentassert_abc/integrations/crewai.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/integrations/crewai.py)
- [src/agentassert_abc/integrations/mcp.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/integrations/mcp.py)
- [src/agentassert_abc/integrations/pydantic_ai.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/integrations/pydantic_ai.py)
- [src/agentassert_abc/compliance/eu_ai_act.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/compliance/eu_ai_act.py)
- [src/agentassert_abc/observability/otel.py](https://github.com/qualixar/agentassert-abc/blob/main/src/agentassert_abc/observability/otel.py)
- [README.md](https://github.com/qualixar/agentassert-abc/blob/main/README.md)
- [examples/06_crewai_integration.py](https://github.com/qualixar/agentassert-abc/blob/main/examples/06_crewai_integration.py)
</details>

# 认证、集成、合规与可视化

## 概述

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` 块联动：

```yaml
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 相乘，给出组合部署阈值：

```python
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]()）：

| 适配器 | 模块 | 典型用法 |
|---|---|---|
| LangGraph | `integrations/langgraph.py` | 节点前置/后置钩子 |
| CrewAI | `integrations/crewai.py` | `Task.guardrail` 字段 |
| MCP Server | `integrations/mcp.py` | JSON-RPC 请求拦截 |
| PydanticAI | `integrations/pydantic_ai.py` | A2A 协议合规桥接 |
| Generic | `integrations/generic.py` | 任意 dict 输出 |

### CrewAI 集成示例

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

```python
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 栈直接对接，无需自建仪表盘。

```mermaid
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 示例](https://github.com/qualixar/agentassert-abc/blob/main/contracts/examples/)
- [可靠性指数与漂移动力学](README.md)
- [arXiv 论文：AgentAssert 形式化框架](https://arxiv.org/abs/2602.22302)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: qualixar/agentassert-abc; human_manual_source: deepwiki_human_wiki -->