AGT 外部评估器交接External Evaluator Handoff依赖审计有界依赖、SDK 摘要助手与零权限交接边界【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit本篇技术指南围绕 agent-governance-toolkitAGT仓库中 docs/dependency-audits/2026-09-03-external-evaluator-handoff.md 这份依赖审计记录展开解读examples/external-evaluator-handoff独立示例新增的两项有界依赖AGT core v5 与 pytest v8的来龙去脉并深入到示例源码、测试用例与底层 SDK 实现说明「外部评估器交接」为何必须站在公共DecisionBOM模型与sha256_jcs摘要助手之上以及该边界如何做到只读、零授权、不影响任何现有包与运行时行为。读完本文你将掌握该示例的依赖约束原理、交接请求的构造与校验方式以及如何安全地运行、测试和评估其变更风险。一、审计背景一次针对独立示例的依赖变更docs/dependency-audits/目录是仓库的依赖审计专区其 README.md 规定任何 PR 只要改动 lockfilerequirements.txt、Cargo.lock、package-lock.json、go.sum、packages.lock.json等或 vendored 内容必须附带一份按YYYY-MM-DD-short-description.md命名的审计文档并包含三个必备小节依赖变更及原因、安全公告相关性、破坏性变更风险评估。2026-09-03 这份审计记录的变更对象是新增的独立示例 examples/external-evaluator-handoff/requirements.txt其内容仅两行agent-governance-toolkit-core5.0.0,6.0 pytest8.0.0,10.0关键结论在文档开头便已点明这两项依赖被隔离在示例内部不改变任何 AGT 包或仓库级运行时依赖图。它既不是安全公告的修复也不引入新的密码学实现。二、两个依赖各自的职责边界1.agent-governance-toolkit-core5.0.0,6.0复用公共 SDK 面该依赖向示例供给两个现成的 SDK 构件DecisionBOM模型决策物料清单模型用于承载一次治理决策的全部可重建因素公共sha256_jcs摘要助手基于 RFC 8785 JSON 规范化JCS的 SHA-256 内容摘要。审计文档特别强调v5 下限是必需的目的是让示例不要绕过 SDK 边界、直接教读者使用裸密码学原语。也就是说示例中任何摘要、任何序列化都应当复用 AGT 公共面而非自造实现。2.pytest8.0.0,10.0仅测试期依赖pytest只用于运行示例的本地回归测试不被可运行示例本身 import。这是一个典型的「测试依赖与运行依赖分离」实践运行示例无需安装测试框架测试环境才需要。三、为何是 v5DecisionBOM 与 sha256_jcs 的源码级依据要理解 v5 下限的含义需要看这两个构件在仓库中的真实定义。DecisionBOM可重建的决策视图DecisionBOM定义于 agent-governance-python/agent-mesh/src/agentmesh/governance/decision_bom.py其模块注释明确其设计哲学可重建视图reconstructible view——不要求在决策时预构建 BOM那会与 action 管线强耦合而是在事后按需查询审计日志、信任分、策略评估、OTel trace 等可观测信号重建完整的决策上下文遵循「不完整但非侵入 完整但侵入」的原则。模型核心包括BOMFieldCategory枚举identity、trust、policy、action、context、outcome、lineage七类与治理关注点对齐BOMField数据类name、category、value、source信号来源、confidence0.0-1.0 置信度默认 1.0、inferred是否为重建推断值DecisionBOM数据类decision_id、timestamp、agent_id、action_requested、outcomeallow/deny/alert、fields、reconstructed_at、sources_queried、completeness_score并提供get_fields_by_category()与to_dict()DecisionBOMReconstructor按 trace_id 或 agent_idtimestamp 从四个信号源audit/trust/policy/trace分阶段重建 BOM并依据REQUIRED_FIELDSagent_identity、trust_score_at_decision、policy_rules_evaluated、action_type、decision_outcome计算completeness_score。交接示例正是围绕这一模型构建的而不是另起炉灶引入第二套审计/策略模型。sha256_jcsRFC 8785 规范化摘要sha256_jcs实现于 agent-governance-python/agent-mesh/src/agentmesh/governance/approval_protocol/digest.py属于 ADR-0030 批准协议的一部分每个批准都通过对请求的规范化序列化做哈希绑定到被审查的精确动作上。该模块不依赖第三方库聚焦实现 RFC 8785 的核心要求对象成员按键的 UTF-16 码元排序_utf16_units无多余空白仅,与:分隔符字符串采用最小 JSON 转义非 ASCII 保留为字面 UTF-8整数无小数点序列化有限浮点用最短往返repr整数型浮点归一化为整数NaN/Infinity一律拒绝_format_numbercanonicalize()返回规范 UTF-8 编码sha256_jcs()返回sha256:小写十六进制前缀形式。模块注释明确指出字节级与非 Python JCS 实现的完全一致被跟踪为跨 SDK 一致性工作ADR-0030 第 6 步而在 Python 治理面内部序列化自洽稳定——在 AGT 内部计算出的摘要在 AGT 内部一定可以复现。这正是动作摘要绑定所要求的最小成立条件。四、交接示例如何使用这两个构件零权限只读边界示例主程序 examples/external-evaluator-handoff/external_evaluator_handoff.py 的模块注释声明了它的边界纪律示例刻意停在互操作边界上——不调用评估器、不修改 AGT 记录、不把评估结果变成治理决策。核心函数build_external_evaluation_request(decisions, *, generated_at, allowed_field_names())的行为要点非空校验决策集为空直接抛ValueError时区强制_utc_timestamp拒绝无时区的时间戳统一转 RFC 3339 UTC 格式00:00替换为Z保证重放无歧义字段白名单默认空集默认不导出任何可选字段避免把任意策略、上下文或 trace 数据误带出边界严格 JSON 检查fail-closed_export_field用json.dumps(..., allow_nanFalse, ensure_asciiFalse, separators(,, :), sort_keysTrue)序列化再反序列化无法严格 JSON 化的字段值直接抛ValueError权威边界固定请求体中的authority_boundary恒为read_only: True、source_records_mutated: False、execution_authorized: False、policy_decision_overridden: False、evaluation_result_is_governance_decision: False——下游评估器收到的是观测既不能授权动作、不能覆盖策略也不能修改源记录内容派生 request_id先对完整请求不含request_id计算sha256_jcs再以eval_hex形式挂到请求上因此标识符本身被排除在自身哈希输入之外。请求的source声明固定为system: agent-governance-toolkit、representation: decision_bom明确交接的是「决策 BOM 表示」框架中立任何外部评估器都可以消费同一观测边界。五、测试如何锁定这些承诺示例测试 examples/external-evaluator-handoff/test_external_evaluator_handoff.py 用 pytest 逐条锁定了上文的承诺这解释了为何 pytest 是测试必需依赖确定性test_handoff_is_deterministic_allowlisted_and_read_only用同一输入两次构造请求断言输出完全相等且源 DecisionBOM 的to_dict()前后一致源不可变摘要正确性test_request_id_uses_the_public_sdk_digest弹出request_id后用公共sha256_jcs对剩余 payload 重算断言request_id eval_ digest验证 request_id 确实来自公共 SDK 助手而非私有实现默认零导出test_handoff_exports_no_optional_fields_by_default断言未传白名单时fields []值脱离detachtest_handoff_detaches_mutable_allowlisted_values_from_source修改导出值不影响源 BOM修改源 BOM 也不影响已导出值——白名单值被拷贝为脱离的严格 JSON 副本fail-closed 校验空决策集、无时区时间戳、非 JSON 可序列化值分别触发三类ValueErrortest_handoff_rejects_empty_decision_set、test_handoff_rejects_timezone_free_timestamps、test_handoff_rejects_non_json_allowlisted_values。六、安全公告相关性不引入新密码学实现审计文档对此节结论明确本次变更不是安全公告修复也没有新增任何密码学实现。内容摘要全部委托给 AGT 既有公共 SDK 助手sha256_jcspytest是纯测试依赖仓库既有的依赖审查与漏洞检查如scripts/下的 check_* 系列脚本与 CI 门禁对解析后的依赖图仍然权威有效。因此该变更的安全面为零增量。七、破坏性变更风险评估low 且 example-local审计结论为风险低、仅限示例内部示例要求 AGT core v5是因为公共摘要助手属于受支持的 v5 表面钉在 AGT core v4 的用户若想运行该示例必须先升级但没有任何既有包、API、策略或运行时行为被改变上界6.0、10.0将解析约束在目前受支持的主版本区间内防止未来主版本漂移导致意外解析。八、验证与回滚可复现的完整闭环审计文档列出的验证覆盖面包括示例测试套件、格式与 lint 检查、严格 JSON 输出、文档链接以及仓库的依赖门禁与「未授权密码学unauthorized-crypto」门禁。你可以按示例 README examples/external-evaluator-handoff/README.md 的指引自行复现# 前置Python 3.11运行时无需 API key 或网络服务 python -m venv .venv source .venv/bin/activate pip install -r examples/external-evaluator-handoff/requirements.txt # 从仓库根目录运行示例打印一个合成请求 python examples/external-evaluator-handoff/external_evaluator_handoff.py # 运行回归测试 PYTHONPATHagent-governance-python/agent-mesh/src \ pytest -q examples/external-evaluator-handoff/test_external_evaluator_handoff.py运行示例时请留意输出中的authority_boundary段其五个布尔字段恒为固定的只读/零授权声明同时注意 README 中的数据与安全提示Decision BOM 字段可能包含策略、上下文或 trace 数据因此除非调用方显式白名单精确字段名否则不导出任何可选字段source_completeness只描述 BOM 重建覆盖率不证明真实世界中某事件正确、已授权或完整sha256_jcs内容是哈希不是签名、不是证明、不是真实性证明示例使用合成标识符与合成值导出真实记录前需评估租户、隐私、留存与跨境合规要求。回滚方案则极为轻量移除该独立示例与这条审计记录即可不涉及任何生产数据或迁移——因为变更从未触及仓库级运行时依赖图。九、总结一次「接口优先」依赖审计的范本这份审计记录的价值在于演示了 AGT 的一个原则性实践接口优先interface-first边界。运行时治理AGT 回答动作是否被允许、应用了哪条策略、观测到哪些治理信号与执行后评估下游评估器跨时间比较多次决策并产出可审查的评估是两个不同的问题评估结论只是独立审查流程的输入不是许可也不覆盖 AGT。本次依赖变更以最小的、被充分论证的两项有界依赖让独立示例在不破坏任何现有面的前提下复用了公共DecisionBOM与sha256_jcs并辅以测试锁定确定性、白名单、不可变与零授权边界——这正是依赖审计应当达到的信息密度变更动机、安全影响、破坏性风险、验证与回滚一应俱全。【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考