项目定位与设计哲学

AgentAssay 是面向非确定性 AI Agent 工作流的统计化回归测试框架,其核心承诺是 "Test More. Spend Less. Ship Confident." 即在不烧毁 token 预算的前提下交付严格的统计保证。该项目是 Qualixar AI Agent 可靠性平台七大产品之一,论文发表于 arXiv:2603.02601。

社区关注的核心痛点是:LangSmith、deepeval、agentrial 等同类工具要么缺乏统计回归检测,要么不支持蜕变测试、CI/CD 部署门禁,而 AgentAssay 在 v0.1.2 生产版本中以 "mypy strict + ruff + Python 3.10/3.11/3.12 全绿" 的硬门禁 CI 流水线弥补了这一空白 资料来源:README.md

六层架构的设计哲学可概括为:第 1~5 层负责让 "每次运行" 都产出严谨结论,第 6 层负责让 "需要多少次运行" 最小化。换言之,前五层是质量保证,顶层是成本优化。

六层架构全景图

资料来源:README.md 中以 ASCII 形式明确划定了六个层级。下面使用 Mermaid 重绘:

flowchart TB
    L6["Layer 6 · Efficiency<br/>Fingerprinting · Budget Optimization<br/>Trace Analysis · Multi-Fidelity · Warm-Start"]
    L5["Layer 5 · Integration<br/>Framework Adapters · pytest Plugin<br/>CLI · Reporting"]
    L4["Layer 4 · Analysis<br/>5D Coverage · Mutation · Metamorphic<br/>Contract Oracle"]
    L3["Layer 3 · Verdicts<br/>Stochastic Verdicts · Deployment Gates"]
    L2["Layer 2 · Statistics<br/>Hypothesis Tests · CIs · SPRT · Effect Size"]
    L1["Layer 1 · Core<br/>Data Models · Execution Engine · Trace Format"]
    L6 --> L5
    L5 --> L4
    L4 --> L3
    L3 --> L2
    L2 --> L1

调用方向:数据从 Layer 1 向上流动,每层为上一层提供更高级别的语义。统计计算 (Layer 2) 在原始执行轨迹 (Layer 1) 之上进行,部署门禁 (Layer 3) 消费统计结论,覆盖率/变异/蜕变分析 (Layer 4) 进一步丰富判定证据,集成层 (Layer 5) 把整套栈暴露给外部用户,而效率层 (Layer 6) 横切所有下层,只决定 "何时停止采样"。

各层关键组件映射

下表把源码中可直接观察到的组件归位到对应层级。所有条目均来自仓库内的实际模块,未做臆测。

资料来源:src/agentassay/mutation/prompt_ops.py、src/agentassay/cli/cmd_report.py()、src/agentassay/persistence/schema.py]()、src/agentassay/persistence/storage.py]()、src/agentassay/dashboard/app.py]()、src/agentassay/integrations/bedrock_adapter.py]()、src/agentassay/integrations/mcp_adapter.py]()、src/agentassay/integrations/semantic_kernel_adapter.py]()。

集成层 (Layer 5) 的横切视图

集成层是仓库内源码最密集的一层,也是用户最常触碰的入口。

框架适配器

四个适配器均继承自 AgentAdapter,并以 framework 字符串字段做自我标识:

• AWS Bedrock:BedrockAgentAdapter 接受 agent_id、agent_alias_id、session_id、region,将每个推理步转为 StepTrace 资料来源:src/agentassay/integrations/bedrock_adapter.py
• MCP:MCPToolsAdapter 同时支持 "direct MCP" 与 "Anthropic" 两种模式 (通过 meta["mcp_mode"] 区分),并要求 mcp 包存在,否则在 run() 调用时才抛错 资料来源:src/agentassay/integrations/mcp_adapter.py
• Semantic Kernel:SemanticKernelAdapter 通过 FunctionInvocationFilter 进行非侵入式轨迹捕获,在钩子不可用时回退为单步 kernel.invoke() 资料来源:src/agentassay/integrations/semantic_kernel_adapter.py
• LangGraph / CrewAI / OpenAI / AutoGen / smolagents:examples/README.md 列出了对应的 examples/framework-specific/*.py,均通过 pip install agentassay[<framework>] 安装可选依赖

CLI 与报告

cli/cmd_report.py 实现了 agentassay report --results trials.json 命令:加载 JSON 结果 → 抽取通过列表 → 计算 Wilson 区间 → 渲染自包含 HTML(包含绿色/红色裁决横幅与通过率进度条)。完整的 CLI 五件套为 run、compare、mutate、coverage、report,外加 test-report 用于测试报告 资料来源:README.md。

Dashboard

dashboard/app.py 是一个 Streamlit 应用,左侧导航栏在 ["Overview", "Test Run", "History", "Fingerprints"] 四页之间切换;底部通过 AGENTASSAY_DB_PATH 环境变量或默认 ~/.agentassay/results.db 初始化 ResultStore 与 QueryAPI 资料来源:src/agentassay/dashboard/app.py。

持久化层支撑裁决与成本核算

persistence/schema.py 用 DDL 定义了八张表:projects、runs、trials、verdicts、coverage、fingerprints、gate_decisions、costs,前八张表组合起来恰好横跨 Layer 1~Layer 6:执行轨迹 (L1)、统计裁决 (L3)、覆盖率 (L4)、指纹与成本 (L6) 资料来源:src/agentassay/persistence/schema.py。

storage.py 的 save_gate_decision() 方法显式接受 decision ∈ {"DEPLOY", "BLOCK", "WARN"} 三值,这是 Layer 3 "三值裁决" 的落地点;save_cost() 接受 input_tokens / output_tokens / total_cost / trial_count,是 Layer 6 成本核算的写入入口 资料来源:src/agentassay/persistence/storage.py。

社区关注与版本里程碑

• v0.1.1 (Initial Public Release):首次发布,主打 5-20x token 成本削减、十种以上框架适配、CI/CD 部署门禁、三值裁决。
• v0.1.2 (Production Release):修复全部 mypy strict 错误、全部 ruff 检查/格式错误;Python 3.10/3.11/3.12 通过测试;CI 流水线把 lint / typecheck / tests 设为硬门禁——这一里程碑对工程可信度意义重大,因为 AI Agent 测试框架本身必须经得起静态检查才能被生产环境采纳 资料来源:community evidence v0.1.2。

See Also

• Stochastic Testing 概念 — 为什么 Agent 测试必须用统计
• Token-Efficient Testing 概念 — 第六层效率优化的核心思想
• Coverage Metrics 概念 — 五维覆盖率模型
• CLI Reference — 五条主命令详解
• Installation Guide — 安装与可选依赖

引擎定位与设计目标

AgentAssay 整体架构分为六层，其中第六层 Efficiency 正是本文的主题。该层位于统计与执行栈之上，不替代下层的假设检验、置信区间或部署门逻辑，而是把"每个场景要跑多少次、用什么模型跑、能不能复用历史结果"这三件事统一抽象为可控的工程对象 资料来源：README.md:60-75。社区公告中强调的 5–20 倍 token 成本下降，正是这一层与 Layers 1–5 协同后获得的累积效果 资料来源：README.md:88-95。

flowchart TD
    A[场景 + 历史 trace] --> B[trace_store: 加载与索引]
    B --> C[fingerprint: 行为指纹]
    C --> D{方差是否稳定?}
    D -- 否 --> E[budget: 估算最小 N]
    D -- 是 --> F[multi_fidelity: 筛选 + 确认]
    E --> F
    F --> G[warm_start: 顺序 SPRT]
    G --> H[regression: 假设检验]
    H --> I{PASS / FAIL / INCONCLUSIVE}
    I -- INCONCLUSIVE --> E
    I -- PASS / FAIL --> J[gate_decisions 持久化]

核心组件

行为指纹（Fingerprinting）

fingerprint 模块把一次 trial 的执行轨迹压缩为可比较的结构化签名，用于跨 run 的等价性判定与漂移检测 资料来源：src/agentassay/efficiency/fingerprint.py:1-40。指纹在持久层有专门的存储表，与运行、试验、裁定并列，说明它被视为一等公民数据 资料来源：src/agentassay/persistence/schema.py:18-32。

自适应预算（Adaptive Budget）

budget 模块根据用户给定的显著性水平、目标通过率与容差，反推达到期望置信区间所需的最小试验数 N，从而避免对低方差代理过度抽样，也避免对高方差代理做出过早裁定 资料来源：src/agentassay/efficiency/budget.py:1-30。这是社区公告中 "5-20x 成本下降" 的主要来源之一 资料来源：README.md:88-95。

多保真度代理（Multi-Fidelity）

multi_fidelity 模块用更便宜的模型做"筛选"、更贵的模型做"确认"。指纹先在便宜模型上生成并比对，仅在指纹出现分歧时才升级到昂贵模型 资料来源：src/agentassay/efficiency/multi_fidelity.py:1-30。这一机制与 trace_store 提供的离线分析能力天然契合：离线 trace 可以在零 token 成本下做指纹比对 资料来源：src/agentassay/efficiency/trace_store.py:1-30。

温启动顺序测试（Warm-Start Sequential）

warm_start 把历史 run 的结果当作先验注入本次统计推断，并结合 SPRT 在累积证据达到阈值时立即给出裁定，从而缩短达到稳定结论所需的试验数 资料来源：src/agentassay/efficiency/warm_start.py:1-30。

裁定与回归检测

三值裁定（Three-Valued Verdicts）

引擎永远输出 PASS、FAIL、INCONCLUSIVE 三种状态之一，而非简单二元结果。INCONCLUSIVE 表示证据不足，需要继续抽样或扩大预算 资料来源：README.md:88-95。最终裁定结果连同置信区间、p 值一起写入 verdicts 表，供后续查询 资料来源：src/agentassay/persistence/schema.py:46-58。

回归检测与部署门

regression 模块对两次 run 的通过率分布做假设检验并报告效应量。当 p 值低于设定 α 且效应量达到业务阈值时，CI/CD 流水线会触发 BLOCK 决策，避免劣质版本上线 资料来源：src/agentassay/efficiency/regression.py:1-30。所有门控决策都会持久化在 gate_decisions 表中，包含 pipeline、commit SHA、PR 号等可追溯字段 资料来源：src/agentassay/persistence/storage.py:60-95。

常见失败模式

• 指纹维度不足：当代理的"行为"主要体现在文本输出而非工具调用时，工具/路径指纹可能饱和，需要补充更多维度的特征。
• 预算估算过紧：在方差估计尚未稳定时就锁定最小 N，会反复触发 INCONCLUSIVE；建议先跑少量 warm-up 试验再调用 budget 资料来源：src/agentassay/efficiency/budget.py:1-30。
• 多保真度错配：筛选模型与确认模型判断不一致时，会出现"通过便宜模型却被贵的模型否定"的情况，需明确两者角色边界 资料来源：src/agentassay/efficiency/multi_fidelity.py:1-30。

另请参阅

• 架构总览与 Layer 1–5 的统计基础
• 置信区间、假设检验与 SPRT 数学定义
• pytest 集成与 CLI 参考

Framework Adapters、CLI、pytest Plugin 与 Dashboard

AgentAssay 的"集成层"承担着把不同 AI 智能体框架接入统一统计测试栈的职责，并提供命令行、pytest 插件与可视化仪表盘等多入口。这一层是研究论文 arXiv:2603.02601 中所述"形式化回归测试框架"在工程上的落点，对应 README 中的第 5 层（Integration）。资料来源：README.md

1. Framework Adapters（框架适配器）

1.1 抽象基类与设计契约

所有适配器都继承自 AgentAdapter（定义于 src/agentassay/integrations/base.py），其核心契约是 run(input_data: dict) -> ExecutionTrace：把外部框架的"运行一次智能体"语义翻译成 AgentAssay 内部的 ExecutionTrace / StepTrace 数据模型。当目标框架的依赖未安装时，会抛出 FrameworkNotInstalledError 并附带安装提示。资料来源：src/agentassay/integrations/base.py

1.2 已支持的框架与安装方式

examples/README.md 列出了 5 个开箱即用适配器以及对应的可选依赖；MCP 与 Semantic Kernel 在后续版本中扩展加入：

资料来源：examples/README.md、src/agentassay/integrations/semantic_kernel_adapter.py、src/agentassay/integrations/mcp_adapter.py

1.3 适配器使用范式

每个示例都遵循同一模式：① 用框架原 API 创建智能体；② 用对应适配器包裹（一行代码）；③ 定义 Scenario；④ 配置 n、显著性水平等统计参数；⑤ 通过 StochasticVerdict 跑多次试验得到 PASS/FAIL/INCONCLUSIVE 三态判决。资料来源：examples/README.md

flowchart LR
    A[Framework Agent] -->|wrap| B(AgentAdapter)
    B -->|run input_data| C[ExecutionTrace]
    C --> D[Stochastic Verdict]
    D --> E{PASS / FAIL / INCONCLUSIVE}
    D --> F[CI / 5D Coverage]
    D --> G[Mutation / Metamorphic]

2. CLI（命令行接口）

src/agentassay/cli/main.py 用 click.group() 暴露 5 个一级命令（加上 dashboard 和 demo），入口为 agentassay --version。版本信息明确归属 Qualixar 与作者。资料来源：src/agentassay/cli/main.py

report 命令会调用 wilson_interval 计算 ci_lower / ci_upper 并嵌入到 HTML 中，可直接用于归档。dashboard 命令支持 --port、--host、--no-browser、--theme（dark/light）等参数。资料来源：src/agentassay/cli/cmd_report.py、src/agentassay/cli/cmd_dashboard.py、src/agentassay/cli/cmd_test_report.py

3. pytest Plugin

通过 pip install agentassay[dev] 即可启用。开发者沿用 @pytest.mark.agentassay(n=30, threshold=0.80) 这样的标记来声明试验次数与通过率阈值，pytest 钩子把统计判决内化为普通断言失败/通过。examples/pytest-plugin/test_my_agent.py 给出了最小可运行模板。资料来源：README.md、examples/README.md

4. Dashboard（仪表盘）

仪表盘基于 Streamlit，入口为 src/agentassay/dashboard/app.py。它通过侧边栏 st.radio 提供四个页面：Overview、Test Run、History、Fingerprints，分别由 view_overview.py、view_test_run.py、view_history.py、view_fingerprints.py 渲染。数据源是本地 SQLite 数据库，路径由环境变量 AGENTASSAY_DB_PATH 控制，默认 ~/.agentassay/results.db，通过 ResultStore 与 QueryAPI 读写。资料来源：src/agentassay/dashboard/app.py

该仪表盘在 v0.1.1 首次公开、v0.1.2 生产化打磨之后仍是 [EXPERIMENTAL] 状态，社区问题多集中在"如何把第三方 trial.json 导入"以及"指纹页面如何解释"上。资料来源：src/agentassay/cli/cmd_dashboard.py

5. 常见失败模式

• 未安装可选依赖：调用 LangGraphAdapter 时若未安装 langgraph，会抛 FrameworkNotInstalledError 并提示 pip install agentassay[langgraph]。资料来源：src/agentassay/integrations/base.py
• Semantic Kernel filter 不可用：semantic_kernel_adapter 会在无 FunctionInvocationFilter 时回退为单步 trace，统计显著性可能降低，需要在 metadata 中显式注明。资料来源：src/agentassay/integrations/semantic_kernel_adapter.py
• results 文件缺失或语法错误：report 命令通过 load_json 捕获 FileNotFoundError 并给出 click.ClickException，用户应先确认 agentassay run 已成功生成 JSON。资料来源：src/agentassay/cli/cmd_report.py

See Also

• 架构与统计栈：Architecture Overview
• 概念：Token-Efficient Testing、Stochastic Testing、Coverage Metrics
• CLI 详细参考：CLI Reference
• 相关论文：arXiv:2603.02601

分析、变异、蜕变测试与部署门控

AgentAssay 在 Layer 3（判定）与 Layer 4（分析）提供了完整的"测试充分性"保障体系。变异测试（Mutation Testing）用于检验测试用例的灵敏度，蜕变测试（Metamorphic Testing）用于在没有真实标签的情况下验证行为不变量，部署门控（Deployment Gates）则把统计判定落地为 CI/CD 流水线中的硬性门槛。本页聚焦这四类机制的源码结构、能力边界与典型用法。

一、变异测试（Mutation Testing）

1.1 抽象基类

MutationOperator 是所有变异算子的统一父类，强制要求 mutate() 返回深拷贝后的 (AgentConfig, TestScenario)，避免污染原始配置。资料来源：src/agentassay/mutation/base.py:30-75。

1.2 算子分类

变异算子按被扰动对象分为四大类（category 字段）：

完整导出列表见 src/agentassay/mutation/__init__.py，并通过 DEFAULT_OPERATORS 常量统一注册。资料来源：src/agentassay/mutation/__init__.py:1-60、src/agentassay/mutation/prompt_ops.py:1-30。

1.3 同义词词典

prompt_ops.py 内置了常见英文动词和强调词的同义替换表，例如 search → look up / query / retrieve、always → consistently / invariably、must → shall / is required to，用于生成语义等价但表层不同的提示。资料来源：src/agentassay/mutation/prompt_ops.py:1-30。

二、蜕变测试（Metamorphic Testing）

蜕变关系被组织成 4 个"族"，通过 src/agentassay/metamorphic/relations.py 的 shim 统一重新导出，保留历史导入路径。资料来源：src/agentassay/metamorphic/relations.py:1-30。

• Family 1 – 置换（Permutation）：InputPermutationRelation、ToolOrderRelation。
• Family 2 – 扰动（Perturbation）：TypographicalPerturbation 通过固定的字符交换表（(a,s)、(e,r) 等 8 对）注入受控拼写错误，验证鲁棒性。资料来源：src/agentassay/metamorphic/perturbation.py:20-40`。
• Family 3 – 组合（Composition）：DecompositionRelation 把复杂任务拆为子任务独立执行，再以 compose_fn 聚合，与一次性执行结果比对一致性。资料来源：src/agentassay/metamorphic/composition.py:1-50`。
• Family 4 – 预言（Oracle）：ConsistencyRelation（默认阈值 0.7，低于其他关系以容忍措辞波动）、MonotonicityRelation（信息增多应得到不更差的结果）。资料来源：src/agentassay/metamorphic/oracle.py:1-60`。

三、判定与持久化（Verdicts & Persistence）

persistence/schema.py 定义了完整的 SQLite DDL，覆盖 8 张表：projects、runs、trials、verdicts、coverage、fingerprints、gate_decisions、costs。其中 gate_decisions 显式存储 pipeline、decision（DEPLOY / BLOCK / WARN）、commit_sha、pr_number 等字段，用于回溯每一次 CI 判定的依据。资料来源：src/agentassay/persistence/schema.py:1-80`。

Storage 类的 save_gate_decision() 提供 9 字段的原子写入接口，参数列表在源码中按"必填 → 可选 ID"顺序排列，返回新决策的 UUID。资料来源：src/agentassay/persistence/storage.py:1-60`。

四、部署门控与 HTML 报告

4.1 流程图

flowchart LR
    A[试验 trials.json] --> B[load_json]
    B --> C[extract_passed_list]
    C --> D[wilson_interval]
    D --> E{判定}
    E -->|CI >= 阈值| F[DEPLOY]
    E -->|CI 不足| G[WARN / INCONCLUSIVE]
    E -->|上限 < 阈值| H[BLOCK]
    F & G & H --> I[Storage.save_gate_decision]
    I --> J[(SQLite gate_decisions)]
    A --> K[_build_html]
    K --> L[report.html]

4.2 CLI 行为

agentassay report --results trials.json 通过 load_json 读取结果，利用 wilson_interval 计算 Wilson 置信区间，再交由 _build_html 生成自包含 HTML 报告（含时间戳 UTC、k/n、点估计与置信区间）。整个流程在 src/agentassay/cli/cmd_report.py 中实现，文件缺失时抛出 FileNotFoundError，JSON 解析失败时给出可读的 ClickException。资料来源：src/agentassay/cli/cmd_report.py:1-80`。

五、版本与社区要点

• v0.1.2（生产发布）：CI 中 lint / typecheck / tests 全部设为硬门槛，mypy 严格模式、ruff 检查零错误。资料来源：v0.1.2 release notes。
• v0.1.1（首次公开）：主打 5–20× Token 成本下降、10 项差异能力（含变异与蜕变测试）。资料来源：v0.1.1 release notes。
• 性能比较表（README 顶部矩阵）显示 AgentAssay 是少数同时支持"统计回归 + 变异 + 蜕变 + 部署门控"的框架。资料来源：README.md。

See Also

• Token-Efficient Testing 概念
• Stochastic Testing 概念
• Coverage Metrics 五维覆盖模型
• Architecture Overview
• CLI Reference

Pitfall Log / 踩坑日志

项目：qualixar/agentassay

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

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

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

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

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

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

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

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

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

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

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

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