AgentGuard

A trace-level diagnosis, evaluation and safe-recovery system for tool-using agents.

AgentGuard 是一套面向工具型 Agent 的轨迹诊断、案例检索、恢复审批、受控执行、回放验证与冻结评测系统。当前的主要监控对象是 FastFix 代码修复 Agent。AgentGuard 的核心诊断、检索、恢复与评测接口建立在版本化 Canonical Trace 之上;FastFix 通过只读适配层接入,是当前主要数据来源。部分 v1.4 数据源生成与冻结工具包含 FastFix-specific integration,但核心诊断与治理模型不依赖 FastFix 内部执行逻辑。

仓库定位是作品集 / 技术审阅快照(portfolio / technical review snapshot): 展示 AgentGuard 自研核心源码、v1.4 冻结评测协议、真实评测结果、设计文档与 Demo Console 截图。本仓库不是完整可一键部署的应用,也不包含私有宿主应用底座(见 UPSTREAM.md 与 SOURCE_AVAILABILITY.md)。

一、Problem

工具型 Agent 在长链路执行中容易出现的故障模式:

故障类	典型表现
`tool_execution_failure`	工具调用本身失败(网络/超时/权限)
`tool_schema_failure`	工具调用参数或返回不符合 schema
`provider_transport_failure`	LLM Provider 传输层错误(限流/超时)
`validation_closure_failure`	修复闭环未能在多轮重试后达成目标
`state_rollback_failure`	状态回滚未真正到达预期快照
`loop_progress_failure`	Agent 在没有进展的死循环中消耗预算
`planning_context_failure`	规划上下文缺失/被错误截断导致决策错误
`security_policy_failure`	安全策略被绕过或未被强制

仅"模型输出故障类别"远不足以可信地修复 Agent,需要一个可审计、可重放、可冻结的系统:

把一次失败的执行归一化为可索引的 Canonical Trace;
用确定性约束引擎对每条证据做结构化判定(无证据时返回 unknown,绝不默认 passed);
用 LangGraph 故障诊断图 + 历史案例 RAG 给出根因与候选恢复动作;
把恢复计划接入人类审批(HITL),只授权,不执行;
恢复执行必须在白名单 + 受控 workspace 内,可回放验证;
整体效果必须在冻结 held-out benchmark 上独立重建评测。

AgentGuard 的所有设计都围绕"可审计性 > 答案美观"。

二、Architecture

flowchart LR
    FF["FastFix / Tool Agent"] -->|执行任务| CT["Canonical Trace<br/>归一化 / 事件 / 摘要"]
    CT --> CE["Constraint Engine<br/>确定性规则集"]
    CE --> EV["Evidence Collection<br/>失败签名 + 关键事件"]
    EV --> RAG["Hybrid RAG<br/>BM25 · Vector · RRF · Rerank"]
    EV --> DX["LangGraph Diagnosis<br/>结构化根因 + abstention"]
    RAG --> DX
    DX --> RP["Recovery Policy<br/>能力注册 + 风险分级"]
    RP --> HITL["Durable HITL<br/>LangGraph interrupt + checkpoint"]
    HITL --> EX["Controlled Execution<br/>白名单 + 受控 workspace"]
    EX --> RP2["Replay + Verification"]
    RP2 --> EV2["Frozen Evaluation<br/>held-out · 唯一 official run"]

要点:

Canonical Trace 是适配器、持久化、约束、诊断、回放和评测之间的稳定边界,Schema 显式版本化(agentguard.canonical-trace.v1)。
Constraint Engine 与 LLM 解耦,无证据时返回 unknown,绝不默认 passed。
LangGraph Diagnosis 受约束引擎可访问的上下文约束,只产出有证据的事件引用。
RAG 自身有 leave-one-family-out 切分,BM25/向量/RRF/Rerank 全部可审计,frozen test 不得进入案例索引。
Recovery 动作来自版本化能力注册表;不确定是否安全时默认进入审批或终止升级,不默认自动执行。
HITL 持久化审批结果是权威事实,Command(resume) 只唤醒,不替代决策。
Controlled Execution 仅在受控 workspace 内执行,且必须可被 Replay 验证。
Frozen Evaluation 一次唯一 official run,filesystem 是权威,adjudication 独立重建指标并与 sealed results 对账。

三、Core Modules

源码位于 src/super_ai/agentguard/,package hierarchy 与私有仓库一致,便于审阅时一一定位。

1. Canonical Trace & FastFix Adapter

schema.py — 版本化 Canonical Trace Schema。
event_identity.py — 事件 ID 规范与持久化 storage alias。
fastfix.py — FastFix 轨迹的只读适配层(纯 AgentGuard 实现,无宿主依赖)。

2. Constraint Engine

确定性规则集 + 隔离执行 + 无证据返回 unknown。模块:constraints/。

文件	作用
`constraints/base.py`	规则基类、证据模型
`constraints/context.py`	约束评估上下文
`constraints/engine.py`	引擎、规则集注册、版本化求值
`constraints/registry.py`	规则集版本与摘要
`constraints/schema.py`	约束结果 Schema
`constraints/rules/{provider,security,state,tool,validation}.py`	五类核心规则(Provider/安全/状态/工具/验证)

3. LangGraph Diagnosis

结构化诊断图,只产出有证据的事件引用。模块:diagnosis/。

文件	作用
`diagnosis/context.py`	Trace → 诊断输入上下文
`diagnosis/graph.py`	LangGraph 故障诊断图编排
`diagnosis/prompts.py`	结构化提示词(版本化)
`diagnosis/schema.py`	诊断结果 Schema
`diagnosis/state.py`	图状态定义
`diagnosis/validator.py`	输出校验(引用必须存在)

4. Hybrid Case RAG

失败案例生命周期严格:candidate → human confirmed → eligible for indexing,frozen test 不得进入索引。模块:retrieval/。

query.py — 查询构造(基于失败签名 + 关键事件)。
leakage.py — leakage guard(阻止 frozen/同 family 泄漏到训练候选)。
fusion.py — BM25 / Vector / RRF 融合。
rerank.py — Rerank 编排。
schema.py — 检索结果 Schema。
service.py — 案例生命周期 + 检索 run + 持久化编排(注: 内部依赖私有宿主向量库 / BM25 实现,见 UPSTREAM.md)。

5. Recovery Policy

recovery/policy.py — 能力注册、风险分级、执行决策(auto_allowed / approval_required / forbidden)。
recovery/schema.py — 恢复计划、审批、审计事件 Schema。

6. Durable HITL Authorization

LangGraph interrupt + 持久化 checkpoint + 异步 resume intent。模块:authorization/。

authorization/graph.py — 授权工作流图(仅授权,不执行恢复动作)。
authorization/state.py — 工作流状态。
authorization/schema.py — Run / Event / ResumeIntent Schema。
authorization/checkpoint.py — checkpoint 持久化(注: SQLAlchemy 持久层在私有宿主,见 UPSTREAM.md)。

7. Controlled Execution

白名单 + 受控 workspace + 幂等执行 + 验证。模块:execution/。

execution/registry.py — executor + fixture 注册表版本。
execution/schema.py — Execution / Attempt / Verification Schema。
execution/workspace.py — 受控 workspace 策略。
execution/service.py — 幂等执行编排。

8. Replay

确定性回放、故障注入、恢复链路验证。模块:replay/。

replay/canonical.py — Canonical replay 重建。
replay/injectors.py — 确定性故障注入器。
replay/fake.py — 测试用 fake executor。
replay/schema.py — Replay Spec / Run / Report Schema。
replay/verifier.py — 恢复结果校验。

9. Frozen Evaluation (重点公开模块)

冻结 held-out 评测、官方 run、adjudication 独立重建。模块:evaluation/。

evaluation/{metrics,metrics_computation,representation_contract,manifest,freeze_gates,readiness,result_models,result_store,validator,report}.py — 指标定义/计算、表示契约、清单、冻结门禁、就绪、结果模型、验证器、官方报告。
evaluation/localization.py、scope.py、inventory.py — 数据分层与作用域。
evaluation/profile_registry.py、execution_profile.py — 执行 profile 注册。
evaluation/preflight.py — preflight(只验证环境与冻结数据)。
evaluation/provenance.py — 数据来源分层。
evaluation/official_runner.py、official_adapters.py — 官方 run 逐样本管线(消化 → 约束 → 诊断 → 检索 → 恢复 → 授权)。
evaluation/v14_official_{protocol,runner,readiness}.py — v1.4 官方协议、Runner、就绪。
evaluation/v14_real_source.py、v14_source_generation.py — v1.4 真实源轨迹再冻结。
evaluation/development_v14*.py — v1.4 development benchmark 配套(用于官方 run 的 heldout 模型定义与消息构造)。
evaluation/candidates/ — 候选集构建、scenario 库、leave-one-family-out 切分。

说明: evaluation/{cli_runner,corpus_bootstrap,frozen_corpus_bootstrap,official_job,official_service,development_v13,v13_*,development_assessment,development_benchmark,freeze_build,freeze_v1,freeze_v1_1,freeze_v1_2}.py 不在公开仓库范围内。它们要么绑私有宿主作业运行时,要么是 v1.x 旧版本或 dev benchmark 内部脚手架。

三·五、Demo Console

以下截图来自 Demo Console 运行实例(演示数据)。UI 截图仅用于功能展示;宿主应用的前端源码未在本仓库中重新分发。

Trace diagnosis & RAG

Evidence-grounded diagnosis

Recovery plan & HITL authorization

More screenshots

Hybrid retrieval & rerank details

Abstention case(主动弃答)

四、Evaluation — v1.4 Frozen Held-Out

数据来源:benchmarks/agentguard/results/frozen-v1.4/ 与 benchmarks/agentguard/adjudication/v1.4/。本节所有数字均逐项独立重建与 sealed results 一致(adjudication 过程见 forensic-report.md 与 metric-reconstruction.json)。

4.1 数据集

维度	数值
Total assets	96
Actionable(至少有一个可执行恢复方向)	64
No-actionable	16
Expected-abstention(模型应正确弃答)	16
Completed assets(模型实际完成)	94
Provider-environment-blocked assets	2

4.2 公开指标

Metric	Value	Num/Den
Macro-F1	0.809	8-class macro
Actionable Precision	1.000	45/45
Actionable Recall	0.703	45/64
Actionable F1	0.826	—
Expected Abstention Correctness	1.000	16/16
False Abstention Rate	0.297	19/64
Root Event Hit	0.563	36/64
Window Exact	0.703	45/64
Validator False Rejection	0.000	0/N
Expansion Repair Rate	0.100	1/10

4.3 执行口径

Official attempt: 1 (rerun = 0)。
Model: Qwen3.5-35B-A3B(具体供应商为 Chat 模型配置入口所选)。
Evaluator commit: d05067579dafecc550f27027277471ac2c2832b3。
Run ID: official-agentguard-frozen-v1.4-run-1。
Window: 2026-08-07T09:12:04Z → 2026-08-07T09:24:41Z。
Filesystem authority: 冻结前协议明确,filesystem 上的官方产物是权威(详见 forensic-report.md 中的 DB/Filesystem Authority 裁定)。
Execution validity: valid_with_execution_limitations(原因: v1.4 by-design 不写 DB run record,2 个 provider 环境失败,token_usage 仅 104/106 上报)。
Capability reporting: valid_with_metric_limitations(LLM 指标可信,token 用量口径不完整)。
独立重建: metric-reconstruction.json 中 17 项指标全部独立重算与 metrics.json 逐项匹配(abs < 1e-12)。
Provider audit: provider-usage-audit.json / provider-retry-audit.jsonl — 总调用 106,限流受影响 2,Retry 2,input_tokens 279,762,output_tokens 25,955。

4.4 不要混为一谈的几件事

Actionable Precision = 1.000 不等于"整体准确率 100%"。它只表示: 模型在"给出可执行恢复方向"这件事上,没有产生 false positive。但模型仍会错过 19/64 个 actionable case(false abstention rate 0.297), 且在 8-class macro 上仍有 3 个类别 recall = 0.5: planning_context_failure、provider_transport_failure、validation_closure_failure。

五、Known Limitations

这是冻结 held-out benchmark,不是线上生产流量。 Actionable Recall 0.703 是在已确认可执行的 64 个 case 上的离线表现,真实线上分布可能更偏或更稀。
仍有 19/64 false abstention。 主要集中在 planning_context_failure / provider_transport_failure / validation_closure_failure / tool_execution_failure / tool_schema_failure 这五类 — 详见 adjudication/v1.4/false-abstention-ledger.json。
RAG 效果依赖历史 failure case corpus。 真实部署需要足够多的、经过人工确认的失败案例索引;冷启动时诊断质量会显著下降。
2 个 asset 因 provider 环境被阻断。 Token 用量仅 104/106 上报。这两项不影响指标,但意味着 96 个 asset 中有 2 个并未真正完成生成,详见 adjudication/v1.4/environment-blocked-analysis.json。
Authorization 仅意味着"允许执行恢复计划",不等于"恢复已成功"。 本仓库提供受控执行(Execution)与 Replay 验证作为恢复完成性的判据,但 v1.4 官方评测并未在受控执行器上端到端跑完整恢复链路(recovery execution 标注为 not_evaluable,详见 official-report.md)。
本仓库不是完整可一键部署的应用。 私有宿主应用的 FastAPI 应用外壳、认证、持久化、向量库、LLM Provider 适配、作业运行时、SSE 接入等基础设施未包含(见 UPSTREAM.md)。Python 文件可以语法编译,但 python -m super_ai.agentguard.evaluation ... 等命令不能完整运行,因为它们依赖未公开的宿主模块。
本仓库不包含前端源码。 Demo Console 的 Vue/TS 实现属于私有宿主应用,仅通过截图(见 docs/images/)展示。
不公开 SQLAlchemy 持久化模型(models.py)。Schema 在 docs/architecture/agentguard-trace-foundation.md 与对应 OpenSpec 中有文档化描述。

六、Public Repository Scope

公开

AgentGuard 后端自研核心源码(src/super_ai/agentguard/)— 选定的 canonical trace、constraint engine、LangGraph diagnosis、case RAG、recovery policy、durable HITL、controlled execution、replay、frozen evaluation 模块。
选定的 AgentGuard 测试(tests/)— 覆盖约束、诊断、检索、恢复、回放、执行、冻结 v1.4、adjudication 等。
v1.4 冻结评测资产 — frozen manifest / dataset / labels / corpus(benchmarks/agentguard/frozen/v1.4/);官方 run / metrics / raw predictions / provider usage / run metadata(benchmarks/agentguard/results/frozen-v1.4/);adjudication 重建产物(benchmarks/agentguard/adjudication/v1.4/);以及 attestations/v1.4/pre-run-freeze-supersession.json。
设计文档 — Trace Foundation、Constraint Engine、Frozen Evaluation Protocol、Stage 0-3 Review。
OpenSpec 精选变更(11 个,见 design/openspec/)— 覆盖 trace foundation → diagnosis graph → case RAG → recovery policy → authorization → execution → replay → evaluation → v1.4 representation contract → v1.4 heldout candidate。
Demo Console 截图(5 张,见 docs/images/)。

不公开

私有宿主应用底座(OnCall / Agent Py)任何文件 — FastAPI 应用外壳、Vue/TS 前端、认证、通用持久化/运行时、通用作业运行时。
apps/backend/src/super_ai/ 下非 agentguard/ 子树(api、auth、chat、documents、jobs、memory、vector_store、aiops、llm、mcp 等)。
原 package.json / pyproject.toml / uv.lock / Docker / Compose / Alembic 基础设施。
apps/backend/src/super_ai/agentguard/models.py(SQLAlchemy 持久化模型)与部分 repository / service integration 层涉及私有宿主持久化边界,因此按保守原则未纳入 public snapshot。
原底座测试、config/user.project.json、本机配置、所有凭据、.env、本地数据库、.workbuddy/、.claude/、.codex/、原 .git/。

关于集成边界

src/super_ai/agentguard/ 内的部分文件保留对私有宿主模块(super_ai.llm、super_ai.memory、super_ai.vector_store、super_ai.jobs、super_ai.api、super_ai.auth、super_ai.project_config 等)的 import,这些 import 表示 AgentGuard 与未公开宿主应用之间的集成边界。对应的宿主实现故意不重新分发。这意味着:

python -m compileall src/ 可以验证语法,但 import super_ai.agentguard.evaluation 之类的运行会在缺宿主模块时失败。
本仓库的语义价值在于代码可读性、设计可追溯、评测结果可信,不是"clone 后即可运行"。

完整说明见 UPSTREAM.md 与 SOURCE_AVAILABILITY.md。

七、Repository Layout

AgentGuard-public/
├── README.md                         本文件
├── UPSTREAM.md                       上游宿主应用来源与不自原创的声明
├── SOURCE_AVAILABILITY.md            再分发可用性说明
├── .gitignore
├── src/super_ai/agentguard/          AgentGuard 后端自研核心源码
│   ├── schema.py · event_identity.py · fastfix.py · __init__.py
│   ├── constraints/                  确定性约束引擎 + rules/{provider,security,state,tool,validation}
│   ├── diagnosis/                    LangGraph 诊断图 + prompts + validator
│   ├── retrieval/                    query / leakage / fusion / rerank / schema / service
│   ├── recovery/                     policy + schema
│   ├── authorization/                graph / state / schema / checkpoint
│   ├── execution/                    registry / schema / workspace / service
│   ├── replay/                       canonical / injectors / fake / schema / verifier
│   └── evaluation/                   冻结评测、官方 run、v1.4 协议、candidates/
├── tests/                            选定的 AgentGuard 测试
├── benchmarks/agentguard/
│   ├── frozen/v1.4/                  冻结输入(manifest / labels / corpus)
│   ├── results/frozen-v1.4/          官方 run 产物(metrics / raw predictions / run metadata)
│   ├── adjudication/v1.4/            独立 forensic adjudication
│   └── attestations/v1.4/            v1.4 pre-run-freeze-supersession
├── docs/
│   ├── architecture/                 trace-foundation · constraint-engine
│   ├── evaluation/                   frozen-evaluation-protocol
│   ├── reviews/                      stage0-3-review
│   └── images/                       5 张 Demo Console 截图
└── design/openspec/                  11 个精选 OpenSpec changes

八、Quick Sanity Check

# 语法编译(仅验证语法,不声称完整应用可运行)
python -m compileall src/

# 扫描典型秘密模式(示例正则已用字符类拆分,避免自匹配)
grep -RInE 'sk-[A-Za-z0-9]{8,}|ghp[_][A-Za-z0-9]{20,}|AKI[A][A-Z0-9]{16}|PRIVATE KEY|BEGIN RSA' src/ tests/ benchmarks/ docs/ design/ 2>/dev/null

# v1.4 官方指标查看
cat benchmarks/agentguard/results/frozen-v1.4/metrics.json | python -m json.tool
cat benchmarks/agentguard/adjudication/v1.4/forensic-report.md

九、What This Repo Is Not

❌ 不声称 FastAPI / Vue / auth / DB / job shell 从零原创(见 UPSTREAM.md)。
❌ 不声称"production-grade" / "enterprise-grade" / "auto-fix all agent failures"。
❌ 不混淆 Actionable Precision = 1.000 与整体准确率。
❌ 不公开任何本地配置、API Key、Token、个人信息、本机绝对路径。
❌ 不公开原私有开发仓库的 .git 历史;本公开仓库使用独立的 Git history。

Navigation Menu

Repository files navigation

AgentGuard

一、Problem

二、Architecture

三、Core Modules

1. Canonical Trace & FastFix Adapter

2. Constraint Engine

3. LangGraph Diagnosis

4. Hybrid Case RAG

5. Recovery Policy

6. Durable HITL Authorization

7. Controlled Execution

8. Replay

9. Frozen Evaluation (重点公开模块)

三·五、Demo Console

Trace diagnosis & RAG

Evidence-grounded diagnosis

Recovery plan & HITL authorization

Hybrid retrieval & rerank details

Abstention case(主动弃答)

四、Evaluation — v1.4 Frozen Held-Out

4.1 数据集

4.2 公开指标

4.3 执行口径

4.4 不要混为一谈的几件事

五、Known Limitations

六、Public Repository Scope

公开

不公开

关于集成边界

七、Repository Layout

八、Quick Sanity Check

九、What This Repo Is Not

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
benchmarks/agentguard		benchmarks/agentguard
design/openspec		design/openspec
docs		docs
src/super_ai/agentguard		src/super_ai/agentguard
tests		tests
.gitignore		.gitignore
README.md		README.md
SOURCE_AVAILABILITY.md		SOURCE_AVAILABILITY.md
UPSTREAM.md		UPSTREAM.md

Folders and files

Latest commit

History

Repository files navigation

AgentGuard

一、Problem

二、Architecture

三、Core Modules

1. Canonical Trace & FastFix Adapter

2. Constraint Engine

3. LangGraph Diagnosis

4. Hybrid Case RAG

5. Recovery Policy

6. Durable HITL Authorization

7. Controlled Execution

8. Replay

9. Frozen Evaluation (重点公开模块)

三·五、Demo Console

Trace diagnosis & RAG

Evidence-grounded diagnosis

Recovery plan & HITL authorization

Hybrid retrieval & rerank details

Abstention case(主动弃答)

四、Evaluation — v1.4 Frozen Held-Out

4.1 数据集

4.2 公开指标

4.3 执行口径

4.4 不要混为一谈的几件事

五、Known Limitations

六、Public Repository Scope

公开

不公开

关于集成边界

七、Repository Layout

八、Quick Sanity Check

九、What This Repo Is Not

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages