Agent Hypervisor 交互笔记本实战执行环、Saga 补偿、Kill Switch 与哈希链审计agent-governance-toolkit【免费下载链接】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-toolkit 仓库中agent-hypervisor包的官方 Jupyter 笔记本 hypervisor-exploration.ipynb 及其配套说明 README 展开带你完整走一遍 hypervisor 运行时的核心机制按信任分分配执行环Execution Rings、带自动补偿的 Saga 工作流、对异常 Agent 的 Kill Switch、分级限流以及防篡改的哈希链审计日志并结合仓库源码解释每个环节背后的实现原理读完后可直接在本地复现全部演示。笔记本定位与内容总览agent-governance-python/agent-hypervisor/notebooks/目录当前提供唯一一个交互式笔记本用于端到端探索 agent-hypervisor 运行时笔记本覆盖内容hypervisor-exploration.ipynb执行环、Saga 补偿、Kill Switch、限流、哈希链审计与 Plotly 可视化的端到端演练笔记本按以下 7 个部分组织与 README 中的 Whats Covered 一一对应Setup— 导入 hypervisor 模块并创建一个 Shared SessionExecution Rings— 基于有效信任分把 Agent 分配到 Ring 0–3并执行环级权限校验Saga Pattern— 定义多步工作流任一步失败时按逆序自动补偿compensationKill Switch— 终止行为异常的 Agent并把在途工作移交给替补 AgentResource Limits— 演示每个 Ring 的差异化限流Audit Trail— 基于 SemanticDelta 的哈希链日志支持链完整性校验Visualization— 用 Plotly 输出环分布、信任分映射与审计时间线图表无 Plotly 时自动降级为文本输出。环境准备与快速开始按 README 的 Quick Start从包根目录启动# From the agent-hypervisor package root cd agent-governance-python/agent-hypervisor pip install -e .[dev] plotly nest-asyncio jupyter notebook notebooks/环境要求Python ≥ 3.11pyproject.toml 中requires-python 3.11agent-hypervisor本包可编辑安装plotly可选——笔记本在未安装时回退到纯文本输出nest-asyncio用于在 Jupyter 单元格中运行协程。这里有两个值得注意的细节.[dev]的作用查看 pyproject.toml 可以看到devextra 提供的是测试/开发依赖pytest、pytest-asyncio、hypothesis、pydantic、fastapi 等而plotly与nest-asyncio不在该 extra 内所以 Quick Start 把它们单独列出安装。文件中的注释还说明对外发布的 wheel 是一个仅依赖的弃用桩redirects toagent-governance-toolkit-core仓库内的src/源码树仍通过可编辑安装的方式被 CI 实际执行因此在仓库内按上述命令本地运行是有效且被验证的路径。路径注入笔记本第一个代码单元格会执行ROOT pathlib.Path.cwd().parent并把ROOT / src插入sys.path。这意味着 Jupyter 必须从notebooks/目录启动与jupyter notebook notebooks/的用法匹配否则无法导入hypervisor包。Setup创建 Hypervisor 与 Session笔记本第一部分创建 hypervisor 实例和会话配置from hypervisor import ( ConsistencyMode, ExecutionRing, Hypervisor, ReversibilityLevel, SessionConfig, ) hv Hypervisor() config SessionConfig( consistency_modeConsistencyMode.STRONG, max_participants10, max_duration_seconds3600, min_eff_score0.3, enable_auditTrue, ) session hv.create_session(config, creator_didagent-root) SESSION_ID session.session.session_idSessionConfig的完整默认值与取值约束定义在 models.py 的 dataclass 中L136–L176字段默认值校验规则consistency_modeConsistencyMode.EVENTUALstrong要求共识或eventualgossipmax_participants10整数范围 1–1000MAX_PARTICIPANTS_LIMITmax_duration_seconds3600整数范围 1–6048007 天MAX_DURATION_LIMITmin_eff_score0.60SESSION_DEFAULT_MIN_EFF_SCORE0.0–1.0 之间的数值enable_auditTrue布尔值所有上限常量集中在 constants.pyL56–L79__post_init__会在构造时做严格类型与范围校验例如参与者超过 1000 或时长超过 7 天都会抛出ValueError。笔记本示例把min_eff_score放宽到 0.3以便让低信任分的agent-deltaσ0.30也能加入会话并进入 Sandbox 环——这正是演示 Ring 3 行为所需。源码层面Hypervisor.create_session的实现在 core.pyL92–L103它构造SharedSessionObject并立即begin_handshake()会话初始状态为CREATED调用activate_session后才进入ACTIVEL186–L189。会话状态机共五种CREATED → HANDSHAKING → ACTIVE → TERMINATING → ARCHIVEDmodels.py 的SessionStateL96–L104。执行环信任分驱动的权限分级笔记本第 2 部分展示 Agent 按有效信任分被分配到 Ring 0–3 的过程。笔记本自带的参考表为Ring级别EFF 分数要求0Root仅创建者1Privileged≥ 0.70 consensus2Standard≥ 0.403Sandbox 0.40而源码中真正生效的阈值以 constants.py 为准L15–L22RING_1_TRUST_THRESHOLD 0.95ExecutionRing.from_eff_score()进入 Ring 1 需要 eff_score 0.95且具备共识RING_2_TRUST_THRESHOLD 0.60eff_score 0.60 进入 Ring 2RING_1_ENFORCER_THRESHOLD 0.70RingEnforcer做访问裁决时使用的 Ring 1 门槛。也就是说笔记本文档表格中的 0.70 对应的是enforcer 裁决阈值与from_eff_score的 0.95 属于两条不同路径——从源码结构看加入会话时的分环ring_enforcer.compute_ring与逐次动作裁决RingEnforcer.check采用了不同粒度的阈值阅读输出时应以实际源码常量为准。动作的风险属性决定最低环笔记本先定义三个不同可逆性的动作read_action ActionDescriptor( action_idread-data, nameRead dataset, execute_api/api/data/read, undo_apiNone, reversibilityReversibilityLevel.FULL, is_read_onlyTrue, ) write_action ActionDescriptor( action_idwrite-report, nameWrite report, execute_api/api/reports/write, undo_api/api/reports/undo, reversibilityReversibilityLevel.PARTIAL, ) admin_action ActionDescriptor( action_iddelete-session, nameDelete session, execute_api/api/session/delete, undo_apiNone, reversibilityReversibilityLevel.NONE, is_adminTrue, )ActionDescriptor是 IATP 能力清单中动作的描述符models.py L207–L260关键字段包括undo_api、undo_window_seconds上限 24 小时、compensation_method、is_read_only、is_admin。其required_ring属性按以下规则推导最低所需环L250–L260is_admin → RING_0_ROOT reversibilityNONE 且非只读 → RING_1_PRIVILEGED is_read_only → RING_3_SANDBOX 其他可逆写操作 → RING_2_STANDARD可逆性还映射到风险权重 ωFULL → (0.1, 0.3)、PARTIAL → (0.5, 0.8)、NONE → (0.9, 1.0)constants.py L84–L91动作的risk_weight取区间中值。加入会话与环级裁决四个不同信任分的 Agent 依次加入agents [ (agent-alpha, 0.95), # 高信任 (agent-beta, 0.72), # 中高 (agent-gamma, 0.55), # 中 (agent-delta, 0.30), # 低信任 → sandbox ] for did, sigma in agents: ring hv.join_session( session_idSESSION_ID, agent_diddid, actionsactions, sigma_rawsigma, )join_session是 hypervisor 的核心入口之一core.py L105–L184 的文档字符串给出了五步流程解析 IATP manifest若提供 adapter 与 manifest可用其sigma_hint作为 σ 回退值把动作注册进 Reversibility Registry模式协商若清单中存在不可逆动作自动把会话强制升级为ConsistencyMode.STRONGL144–L146——这是不可逆操作必须强一致的硬约束校验 Agent 的 DID 交易历史解析有效分数并分配环若历史校验未通过probationary agent一律降入 Ring 3 SandboxL172–L174。得到环之后笔记本用RingEnforcer做逐动作裁决enforcer RingEnforcer() for did, sigma in agents: ring assigned_rings[did] for action in actions: result enforcer.check( agent_ringring, actionaction, eff_scoresigma, has_consensusFalse, has_sre_witnessFalse, ) status allowed if result.allowed else deniedcheck的输入除了 Agent 当前环与动作还包括eff_score、has_consensus、has_sre_witness等上下文标志——从签名可以推断Ring 1 的不可逆操作需要共识、Ring 0 的管理操作需要 SRE Witness 参与这与 models.py 中ExecutionRing的文档字符串Ring 0 requires SRE Witness、Ring 1 requires consensus一致。RingEnforcer实现在 enforcer.py配套测试见 test_ring_enforcement.py。Saga 模式失败自动补偿第 3 部分演示多步工作流。先激活会话hv.activate_session(SESSION_ID) # 状态 HANDSHAKING → ACTIVE然后创建 Saga 并加入三个步骤orch session.saga saga orch.create_saga(session_idSESSION_ID) step1 orch.add_step(saga_idsaga.saga_id, action_idextract, agent_didagent-alpha, execute_api/api/extract, undo_api/api/extract/undo) step2 orch.add_step(saga_idsaga.saga_id, action_idtransform, agent_didagent-beta, execute_api/api/transform, undo_api/api/transform/undo) step3 orch.add_step(saga_idsaga.saga_id, action_idload, agent_didagent-gamma, execute_api/api/load, undo_api/api/load/undo)前两步正常执行第三步故意抛错async def execute_load_fail(): raise RuntimeError(Disk full — cannot load data) try: run(orch.execute_step(saga.saga_id, step3.step_id, executorexecute_load_fail)) except Exception as exc: print(fStep 3 FAILED: {exc})失败后saga.state进入补偿流程已成功的extract、transform步骤按逆序触发各自的undo_api。笔记本通过run()辅助函数内部使用nest_asynciorun_until_complete在同步单元格中驱动这些异步执行器。Saga 编排器位于 orchestrator.py 与 state_machine.py默认参数见 constants.py L45–L52每步最多重试 2 次SAGA_DEFAULT_MAX_RETRIES、重试间隔 1.0 秒且按尝试次数倍增、单步超时 300 秒SAGA_DEFAULT_STEP_TIMEOUT_SECONDS。行为可由 test_saga.py 交叉验证另有一个独立教程 saga-compensation 可进一步阅读。Kill Switch终止异常 Agent 并移交在途工作第 4 部分演示安全终止ks KillSwitch() # 先注册一个替补 Agent ks.register_substitute(session_idSESSION_ID, agent_didagent-beta) kill_result ks.kill( agent_didagent-delta, session_idSESSION_ID, reasonKillReason.BEHAVIORAL_DRIFT, in_flight_steps[], detailsTrust score dropped below threshold after anomalous writes, ) print(fKill ID : {kill_result.kill_id}) print(fReason : {kill_result.reason.name}) print(fCompensation : {kill_result.compensation_triggered}) print(fTotal kills : {ks.total_kills})要点KillSwitch支持register_substitute预先登记替补者kill()接收被终止者 DID、会话 ID、终止原因枚举示例使用KillReason.BEHAVIORAL_DRIFT、在途步骤列表与人类可读的详情返回包含kill_id、时间戳、compensation_triggered等字段的结果对象total_kills累计历史终止次数。实现见 kill_switch.py单测 test_kill_switch.py 覆盖了终止与移交路径。资源限制按环分级的限流演示第 5 部分用一个简化的窗口计数器演示环越低、配额越小的思想RATE_LIMITS { ExecutionRing.RING_0_ROOT: 100, # ops / window ExecutionRing.RING_1_PRIVILEGED: 50, ExecutionRing.RING_2_STANDARD: 20, ExecutionRing.RING_3_SANDBOX: 5, }每个 Agent 模拟 25 次操作低信任的 Ring 3 Agent 很快被拒5 次通过、20 次拒绝高信任 Agent 则全部放行最终打印每个 Agent 的 accepted/denied 统计。需要注意笔记本里的数字是教学用的每窗口操作数hypervisor 内置限流器的生产默认值是请求/秒 突发容量元组定义在 constants.py L27–L40Ring默认限流 (req/s, burst)Ring 0 (Root)(100.0, 200.0)Ring 1 (Privileged)(50.0, 100.0)Ring 2 (Standard)(20.0, 40.0)Ring 3 (Sandbox)(5.0, 10.0)未知环回退同 Ring 2两套数值在量级上刻意保持一致100/50/20/5但实际部署时应以security/rate_limiter.py的 (rate, burst) 语义为准测试见 test_rate_limiter.py。审计日志防篡改的哈希链第 6 部分展示 Delta 审计引擎from hypervisor.audit.delta import DeltaEngine, VFSChange delta_engine DeltaEngine(session_idSESSION_ID) # agent-alpha 创建 /data/report.mdcontent_hashabc123 # agent-beta 更新 /data/report.mdprevious_hashabc123 → def456 # agent-gamma 创建 /data/summary.txtcontent_hashghi789 for agent_did, changes in changes_list: delta delta_engine.capture(agent_didagent_did, changeschanges) print(fChain valid : {delta_engine.verify_chain()}) print(fChain root : {delta_engine.compute_hash_chain_root()[:32]}…)机制拆解实现见 delta.pyVFSChangeL19描述一次虚拟文件系统的变更字段为path、operationcreate/update 等、content_hash、previous_hash、agent_did——即每个变更自带内容指纹与其前驱指纹SemanticDeltaL30一个轮次内的全部变更打包成一条语义增量带turn_id、delta_hash与parent_hashDeltaEngineL77capture()L85把某 Agent 一轮的变更铸造成新 delta 并链接到链尾verify_chain()L113返回(bool, str | None)校验整条链的完整性compute_hash_chain_root()L107计算链根摘要可作为整条审计日志的密码学承诺。由于每条 delta 通过parent_hash指向上一条、并通过content_hash串联文件版本任何历史篡改都会使链校验失败——这正是tamper-evident可检测篡改的含义。会话终止时这一机制被自动收尾core.py 的terminate_sessionL191–L204在归档会话前调用_commit_audit返回delta_engine.compute_hash_chain_root()若enable_auditFalse则返回None。审计相关行为另有 test_audit.py 覆盖。可视化与收尾第 7 部分在安装了plotly时渲染三张图否则打印等价的文本摘要环分布 限流柱状图make_subplots左侧为 Agent 环分布饼图Ring 0 红 / Ring 1 橙 / Ring 2 蓝 / Ring 3 灰右侧为每环操作配额柱状图信任分 → 环映射散点图x 轴为原始信任分 σy 轴为环编号0 置顶点色按 RdYlGn 色标映射 σ 值审计链时间线横轴 turn、纵轴 Agent点上标注 delta 哈希前缀直观展示哈希链的串联关系。收尾单元格终止会话并取得最终链根root_hash hv.terminate_session(SESSION_ID) print(fFinal hash-chain root: {root_hash})验证路径与延伸阅读笔记本中每个机制在仓库里都有可执行的测试与文档支撑建议按主题深入环与裁决test_ring_enforcement.py、test_rings.py、教程 execution-rings-workflowSagatest_saga.py、test_saga_span_exporter.pyKill Switch 与限流test_kill_switch.py、test_rate_limiter.py审计test_audit.pyAPI 参考与完整演示api-reference.md、examples/demo.py。小结hypervisor-exploration.ipynb用一条创建会话 → 分环 → 跑 Saga → 终止异常 Agent → 限流 → 审计 → 可视化的完整叙事串起了 agent-hypervisor 的核心治理能力信任分驱动的 Ring 0–3 权限模型、不可逆动作强制强一致的会话协商、失败即逆序补偿的 Saga 编排、可登记替补的 Kill Switch以及可校验、可提交链根的哈希链审计日志。所有数值阈值0.95/0.60/0.70 环阈值、(rate, burst) 限流、2 次重试、24 小时撤销窗口都集中在 constants.py 单一位置维护复现实验或做策略调参时这是第一站。【免费下载链接】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），仅供参考 Agent Hypervisor 交互笔记本实战：执行环、Saga 补偿、Kill Switch 与哈希链审计（agent-governance-toolkit）
Agent Hypervisor 交互笔记本实战执行环、Saga 补偿、Kill Switch 与哈希链审计agent-governance-toolkit【免费下载链接】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-toolkit 仓库中agent-hypervisor包的官方 Jupyter 笔记本 hypervisor-exploration.ipynb 及其配套说明 README 展开带你完整走一遍 hypervisor 运行时的核心机制按信任分分配执行环Execution Rings、带自动补偿的 Saga 工作流、对异常 Agent 的 Kill Switch、分级限流以及防篡改的哈希链审计日志并结合仓库源码解释每个环节背后的实现原理读完后可直接在本地复现全部演示。笔记本定位与内容总览agent-governance-python/agent-hypervisor/notebooks/目录当前提供唯一一个交互式笔记本用于端到端探索 agent-hypervisor 运行时笔记本覆盖内容hypervisor-exploration.ipynb执行环、Saga 补偿、Kill Switch、限流、哈希链审计与 Plotly 可视化的端到端演练笔记本按以下 7 个部分组织与 README 中的 Whats Covered 一一对应Setup— 导入 hypervisor 模块并创建一个 Shared SessionExecution Rings— 基于有效信任分把 Agent 分配到 Ring 0–3并执行环级权限校验Saga Pattern— 定义多步工作流任一步失败时按逆序自动补偿compensationKill Switch— 终止行为异常的 Agent并把在途工作移交给替补 AgentResource Limits— 演示每个 Ring 的差异化限流Audit Trail— 基于 SemanticDelta 的哈希链日志支持链完整性校验Visualization— 用 Plotly 输出环分布、信任分映射与审计时间线图表无 Plotly 时自动降级为文本输出。环境准备与快速开始按 README 的 Quick Start从包根目录启动# From the agent-hypervisor package root cd agent-governance-python/agent-hypervisor pip install -e .[dev] plotly nest-asyncio jupyter notebook notebooks/环境要求Python ≥ 3.11pyproject.toml 中requires-python 3.11agent-hypervisor本包可编辑安装plotly可选——笔记本在未安装时回退到纯文本输出nest-asyncio用于在 Jupyter 单元格中运行协程。这里有两个值得注意的细节.[dev]的作用查看 pyproject.toml 可以看到devextra 提供的是测试/开发依赖pytest、pytest-asyncio、hypothesis、pydantic、fastapi 等而plotly与nest-asyncio不在该 extra 内所以 Quick Start 把它们单独列出安装。文件中的注释还说明对外发布的 wheel 是一个仅依赖的弃用桩redirects toagent-governance-toolkit-core仓库内的src/源码树仍通过可编辑安装的方式被 CI 实际执行因此在仓库内按上述命令本地运行是有效且被验证的路径。路径注入笔记本第一个代码单元格会执行ROOT pathlib.Path.cwd().parent并把ROOT / src插入sys.path。这意味着 Jupyter 必须从notebooks/目录启动与jupyter notebook notebooks/的用法匹配否则无法导入hypervisor包。Setup创建 Hypervisor 与 Session笔记本第一部分创建 hypervisor 实例和会话配置from hypervisor import ( ConsistencyMode, ExecutionRing, Hypervisor, ReversibilityLevel, SessionConfig, ) hv Hypervisor() config SessionConfig( consistency_modeConsistencyMode.STRONG, max_participants10, max_duration_seconds3600, min_eff_score0.3, enable_auditTrue, ) session hv.create_session(config, creator_didagent-root) SESSION_ID session.session.session_idSessionConfig的完整默认值与取值约束定义在 models.py 的 dataclass 中L136–L176字段默认值校验规则consistency_modeConsistencyMode.EVENTUALstrong要求共识或eventualgossipmax_participants10整数范围 1–1000MAX_PARTICIPANTS_LIMITmax_duration_seconds3600整数范围 1–6048007 天MAX_DURATION_LIMITmin_eff_score0.60SESSION_DEFAULT_MIN_EFF_SCORE0.0–1.0 之间的数值enable_auditTrue布尔值所有上限常量集中在 constants.pyL56–L79__post_init__会在构造时做严格类型与范围校验例如参与者超过 1000 或时长超过 7 天都会抛出ValueError。笔记本示例把min_eff_score放宽到 0.3以便让低信任分的agent-deltaσ0.30也能加入会话并进入 Sandbox 环——这正是演示 Ring 3 行为所需。源码层面Hypervisor.create_session的实现在 core.pyL92–L103它构造SharedSessionObject并立即begin_handshake()会话初始状态为CREATED调用activate_session后才进入ACTIVEL186–L189。会话状态机共五种CREATED → HANDSHAKING → ACTIVE → TERMINATING → ARCHIVEDmodels.py 的SessionStateL96–L104。执行环信任分驱动的权限分级笔记本第 2 部分展示 Agent 按有效信任分被分配到 Ring 0–3 的过程。笔记本自带的参考表为Ring级别EFF 分数要求0Root仅创建者1Privileged≥ 0.70 consensus2Standard≥ 0.403Sandbox 0.40而源码中真正生效的阈值以 constants.py 为准L15–L22RING_1_TRUST_THRESHOLD 0.95ExecutionRing.from_eff_score()进入 Ring 1 需要 eff_score 0.95且具备共识RING_2_TRUST_THRESHOLD 0.60eff_score 0.60 进入 Ring 2RING_1_ENFORCER_THRESHOLD 0.70RingEnforcer做访问裁决时使用的 Ring 1 门槛。也就是说笔记本文档表格中的 0.70 对应的是enforcer 裁决阈值与from_eff_score的 0.95 属于两条不同路径——从源码结构看加入会话时的分环ring_enforcer.compute_ring与逐次动作裁决RingEnforcer.check采用了不同粒度的阈值阅读输出时应以实际源码常量为准。动作的风险属性决定最低环笔记本先定义三个不同可逆性的动作read_action ActionDescriptor( action_idread-data, nameRead dataset, execute_api/api/data/read, undo_apiNone, reversibilityReversibilityLevel.FULL, is_read_onlyTrue, ) write_action ActionDescriptor( action_idwrite-report, nameWrite report, execute_api/api/reports/write, undo_api/api/reports/undo, reversibilityReversibilityLevel.PARTIAL, ) admin_action ActionDescriptor( action_iddelete-session, nameDelete session, execute_api/api/session/delete, undo_apiNone, reversibilityReversibilityLevel.NONE, is_adminTrue, )ActionDescriptor是 IATP 能力清单中动作的描述符models.py L207–L260关键字段包括undo_api、undo_window_seconds上限 24 小时、compensation_method、is_read_only、is_admin。其required_ring属性按以下规则推导最低所需环L250–L260is_admin → RING_0_ROOT reversibilityNONE 且非只读 → RING_1_PRIVILEGED is_read_only → RING_3_SANDBOX 其他可逆写操作 → RING_2_STANDARD可逆性还映射到风险权重 ωFULL → (0.1, 0.3)、PARTIAL → (0.5, 0.8)、NONE → (0.9, 1.0)constants.py L84–L91动作的risk_weight取区间中值。加入会话与环级裁决四个不同信任分的 Agent 依次加入agents [ (agent-alpha, 0.95), # 高信任 (agent-beta, 0.72), # 中高 (agent-gamma, 0.55), # 中 (agent-delta, 0.30), # 低信任 → sandbox ] for did, sigma in agents: ring hv.join_session( session_idSESSION_ID, agent_diddid, actionsactions, sigma_rawsigma, )join_session是 hypervisor 的核心入口之一core.py L105–L184 的文档字符串给出了五步流程解析 IATP manifest若提供 adapter 与 manifest可用其sigma_hint作为 σ 回退值把动作注册进 Reversibility Registry模式协商若清单中存在不可逆动作自动把会话强制升级为ConsistencyMode.STRONGL144–L146——这是不可逆操作必须强一致的硬约束校验 Agent 的 DID 交易历史解析有效分数并分配环若历史校验未通过probationary agent一律降入 Ring 3 SandboxL172–L174。得到环之后笔记本用RingEnforcer做逐动作裁决enforcer RingEnforcer() for did, sigma in agents: ring assigned_rings[did] for action in actions: result enforcer.check( agent_ringring, actionaction, eff_scoresigma, has_consensusFalse, has_sre_witnessFalse, ) status allowed if result.allowed else deniedcheck的输入除了 Agent 当前环与动作还包括eff_score、has_consensus、has_sre_witness等上下文标志——从签名可以推断Ring 1 的不可逆操作需要共识、Ring 0 的管理操作需要 SRE Witness 参与这与 models.py 中ExecutionRing的文档字符串Ring 0 requires SRE Witness、Ring 1 requires consensus一致。RingEnforcer实现在 enforcer.py配套测试见 test_ring_enforcement.py。Saga 模式失败自动补偿第 3 部分演示多步工作流。先激活会话hv.activate_session(SESSION_ID) # 状态 HANDSHAKING → ACTIVE然后创建 Saga 并加入三个步骤orch session.saga saga orch.create_saga(session_idSESSION_ID) step1 orch.add_step(saga_idsaga.saga_id, action_idextract, agent_didagent-alpha, execute_api/api/extract, undo_api/api/extract/undo) step2 orch.add_step(saga_idsaga.saga_id, action_idtransform, agent_didagent-beta, execute_api/api/transform, undo_api/api/transform/undo) step3 orch.add_step(saga_idsaga.saga_id, action_idload, agent_didagent-gamma, execute_api/api/load, undo_api/api/load/undo)前两步正常执行第三步故意抛错async def execute_load_fail(): raise RuntimeError(Disk full — cannot load data) try: run(orch.execute_step(saga.saga_id, step3.step_id, executorexecute_load_fail)) except Exception as exc: print(fStep 3 FAILED: {exc})失败后saga.state进入补偿流程已成功的extract、transform步骤按逆序触发各自的undo_api。笔记本通过run()辅助函数内部使用nest_asynciorun_until_complete在同步单元格中驱动这些异步执行器。Saga 编排器位于 orchestrator.py 与 state_machine.py默认参数见 constants.py L45–L52每步最多重试 2 次SAGA_DEFAULT_MAX_RETRIES、重试间隔 1.0 秒且按尝试次数倍增、单步超时 300 秒SAGA_DEFAULT_STEP_TIMEOUT_SECONDS。行为可由 test_saga.py 交叉验证另有一个独立教程 saga-compensation 可进一步阅读。Kill Switch终止异常 Agent 并移交在途工作第 4 部分演示安全终止ks KillSwitch() # 先注册一个替补 Agent ks.register_substitute(session_idSESSION_ID, agent_didagent-beta) kill_result ks.kill( agent_didagent-delta, session_idSESSION_ID, reasonKillReason.BEHAVIORAL_DRIFT, in_flight_steps[], detailsTrust score dropped below threshold after anomalous writes, ) print(fKill ID : {kill_result.kill_id}) print(fReason : {kill_result.reason.name}) print(fCompensation : {kill_result.compensation_triggered}) print(fTotal kills : {ks.total_kills})要点KillSwitch支持register_substitute预先登记替补者kill()接收被终止者 DID、会话 ID、终止原因枚举示例使用KillReason.BEHAVIORAL_DRIFT、在途步骤列表与人类可读的详情返回包含kill_id、时间戳、compensation_triggered等字段的结果对象total_kills累计历史终止次数。实现见 kill_switch.py单测 test_kill_switch.py 覆盖了终止与移交路径。资源限制按环分级的限流演示第 5 部分用一个简化的窗口计数器演示环越低、配额越小的思想RATE_LIMITS { ExecutionRing.RING_0_ROOT: 100, # ops / window ExecutionRing.RING_1_PRIVILEGED: 50, ExecutionRing.RING_2_STANDARD: 20, ExecutionRing.RING_3_SANDBOX: 5, }每个 Agent 模拟 25 次操作低信任的 Ring 3 Agent 很快被拒5 次通过、20 次拒绝高信任 Agent 则全部放行最终打印每个 Agent 的 accepted/denied 统计。需要注意笔记本里的数字是教学用的每窗口操作数hypervisor 内置限流器的生产默认值是请求/秒 突发容量元组定义在 constants.py L27–L40Ring默认限流 (req/s, burst)Ring 0 (Root)(100.0, 200.0)Ring 1 (Privileged)(50.0, 100.0)Ring 2 (Standard)(20.0, 40.0)Ring 3 (Sandbox)(5.0, 10.0)未知环回退同 Ring 2两套数值在量级上刻意保持一致100/50/20/5但实际部署时应以security/rate_limiter.py的 (rate, burst) 语义为准测试见 test_rate_limiter.py。审计日志防篡改的哈希链第 6 部分展示 Delta 审计引擎from hypervisor.audit.delta import DeltaEngine, VFSChange delta_engine DeltaEngine(session_idSESSION_ID) # agent-alpha 创建 /data/report.mdcontent_hashabc123 # agent-beta 更新 /data/report.mdprevious_hashabc123 → def456 # agent-gamma 创建 /data/summary.txtcontent_hashghi789 for agent_did, changes in changes_list: delta delta_engine.capture(agent_didagent_did, changeschanges) print(fChain valid : {delta_engine.verify_chain()}) print(fChain root : {delta_engine.compute_hash_chain_root()[:32]}…)机制拆解实现见 delta.pyVFSChangeL19描述一次虚拟文件系统的变更字段为path、operationcreate/update 等、content_hash、previous_hash、agent_did——即每个变更自带内容指纹与其前驱指纹SemanticDeltaL30一个轮次内的全部变更打包成一条语义增量带turn_id、delta_hash与parent_hashDeltaEngineL77capture()L85把某 Agent 一轮的变更铸造成新 delta 并链接到链尾verify_chain()L113返回(bool, str | None)校验整条链的完整性compute_hash_chain_root()L107计算链根摘要可作为整条审计日志的密码学承诺。由于每条 delta 通过parent_hash指向上一条、并通过content_hash串联文件版本任何历史篡改都会使链校验失败——这正是tamper-evident可检测篡改的含义。会话终止时这一机制被自动收尾core.py 的terminate_sessionL191–L204在归档会话前调用_commit_audit返回delta_engine.compute_hash_chain_root()若enable_auditFalse则返回None。审计相关行为另有 test_audit.py 覆盖。可视化与收尾第 7 部分在安装了plotly时渲染三张图否则打印等价的文本摘要环分布 限流柱状图make_subplots左侧为 Agent 环分布饼图Ring 0 红 / Ring 1 橙 / Ring 2 蓝 / Ring 3 灰右侧为每环操作配额柱状图信任分 → 环映射散点图x 轴为原始信任分 σy 轴为环编号0 置顶点色按 RdYlGn 色标映射 σ 值审计链时间线横轴 turn、纵轴 Agent点上标注 delta 哈希前缀直观展示哈希链的串联关系。收尾单元格终止会话并取得最终链根root_hash hv.terminate_session(SESSION_ID) print(fFinal hash-chain root: {root_hash})验证路径与延伸阅读笔记本中每个机制在仓库里都有可执行的测试与文档支撑建议按主题深入环与裁决test_ring_enforcement.py、test_rings.py、教程 execution-rings-workflowSagatest_saga.py、test_saga_span_exporter.pyKill Switch 与限流test_kill_switch.py、test_rate_limiter.py审计test_audit.pyAPI 参考与完整演示api-reference.md、examples/demo.py。小结hypervisor-exploration.ipynb用一条创建会话 → 分环 → 跑 Saga → 终止异常 Agent → 限流 → 审计 → 可视化的完整叙事串起了 agent-hypervisor 的核心治理能力信任分驱动的 Ring 0–3 权限模型、不可逆动作强制强一致的会话协商、失败即逆序补偿的 Saga 编排、可登记替补的 Kill Switch以及可校验、可提交链根的哈希链审计日志。所有数值阈值0.95/0.60/0.70 环阈值、(rate, burst) 限流、2 次重试、24 小时撤销窗口都集中在 constants.py 单一位置维护复现实验或做策略调参时这是第一站。【免费下载链接】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），仅供参考