Agent Hypervisor 运行时治理指南用执行环、Saga 补偿与哈希链审计驯服失控的 AI Agent【免费下载链接】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 仓库中 docs/packages/agent-hypervisor.md 的公开预览文档结合 agent-hypervisor 的完整 Python 源码系统讲解如何在多 Agent 共享会话中落地运行时治理从信任分数到执行环Execution Ring的动态权限划分、带 TTL 的临时提权sudo、Saga 事务补偿、Kill Switch 熔断、令牌桶限流以及基于 SHA-256 哈希链的防篡改审计。读完本文你将能够独立搭建一个隔离的治理会话为 Agent 分配合适的执行环并复现完整的失控终止 步骤交接 逆序补偿闭环。说明文档明确标注agent-hypervisor已不再作为独立 PyPI 包发布新项目请安装agent-governance-toolkit-core或完整工具包本目录源码仍持续测试是本文所有运行时特性的权威实现依据。为什么需要 Agent Hypervisor问题AI Agent 默认拥有无限资源、没有隔离、没有 Kill Switch。共享会话中一个失控的 Agent 就能提权、污染状态甚至让故障级联扩散到整个系统。方案一个运行时超管——执行环、资源上限、Saga 补偿与运行时治理提供 Kill Switch 和爆炸半径blast-radius收敛。与操作系统概念的映射OS / VM HypervisorAgent Hypervisor为什么重要CPU 特权环Ring 0-3执行环基于信任分数的特权等级分级授权而非二元放行/拒绝进程隔离会话隔离VFS 命名空间 DID 绑定身份失控 Agent 无法污染其他会话系统调用Saga 事务多步操作自动回滚失败的工作流自我撤销看门狗定时器Kill Switch优雅终止 步骤交接无数据丢失地停下失控 Agent审计日志哈希链 delta 轨迹防篡改取证记录证明到底发生了什么快速上手pip install agent-governance-toolkit-corefrom hypervisor import Hypervisor, SessionConfig, ConsistencyMode hv Hypervisor() # 创建启用治理的隔离会话 session hv.create_session( configSessionConfig(enable_auditTrue), creator_diddid:mesh:admin, ) # Agent 加入根据信任分数自动分配执行环 ring hv.join_session( session.sso.session_id, did:mesh:agent-1, sigma_raw0.85, ) # RING_2_STANDARD (trusted agent) # 激活会话并运行受治理的 Saga hv.activate_session(session.sso.session_id) saga session.saga.create_saga(session.sso.session_id) step session.saga.add_step( saga.saga_id, draft_email, did:mesh:agent-1, execute_api/api/draft, undo_api/api/undo-draft, timeout_seconds30, max_retries2, ) result await session.saga.execute_step( saga.saga_id, step.step_id, executordraft_email, ) # 终止会话返回防篡改审计哈希根 hash_root hv.terminate_session(session.sso.session_id)这段代码背后对应 core.py 中Hypervisor的完整调用链create_session创建SharedSessionObject并进入握手态join_session经过 IATP 清单解析、动作注册、一致性模式协商、DID 历史校验、信任分数解析五步后由RingEnforcer.compute_ring()计算环级terminate_session会调用_commit_audit()计算审计哈希链根若enable_auditFalse则返回None。配置指南Agent 配置与执行环分配Agent 加入会话时依据信任分数eff_score被分配执行环可用nexus外部信任评分后端、policy_check行为验证适配器、iatp能力清单解析器三个可选适配器增强判定from hypervisor import Hypervisor, SessionConfig, ConsistencyMode, ExecutionRing hv Hypervisor( nexusNone, # 外部信任评分后端 policy_checkNone, # 行为验证适配器 iatpNone, # 能力清单解析器 ) session hv.create_session( configSessionConfig( consistency_modeConsistencyMode.EVENTUAL, # 或 STRONG max_participants10, # 1-1000 max_duration_seconds3600, # 1-604,800最长 7 天 min_eff_score0.60, # 加入会话的最低信任分 enable_auditTrue, # 哈希链审计轨迹 ), creator_diddid:mesh:admin, ) ring hv.join_session( session.sso.session_id, did:mesh:agent-1, sigma_raw0.85, # 原始信任分 [0.0-1.0] ) # 环级分配阈值 # eff_score 0.95 共识 - RING_1_PRIVILEGED # eff_score 0.60 - RING_2_STANDARD # 其余情况 - RING_3_SANDBOX默认这些阈值并非写死在业务代码里而是集中在 constants.py 中RING_1_TRUST_THRESHOLD 0.95、RING_2_TRUST_THRESHOLD 0.60。环级判定逻辑在 models.py 的ExecutionRing.from_eff_score()eff_score 0.95 且 has_consensus才能进 Ring 1 0.60进 Ring 2否则落入 Ring 3 Sandbox。值得注意的细节源自join_session实现若提供了nexus适配器且显式传入sigma_raw最终取min(sigma_raw, nexus_sigma)——保守取低值若 DID 历史校验verification.is_trustworthy不通过即使信任分再高也会被强制压回RING_3_SANDBOXprobationary 机制会话中存在不可逆动作时会话会强制切换为ConsistencyMode.STRONG。每个执行环还绑定了一组资源约束见 enforcer.py 的RING_CONSTRAINTS表环级网络文件系统子进程最大并发工具Ring 0 Root允许可写full允许32Ring 1 Privileged允许可写full允许16Ring 2 Standard允许可配置白名单可写scoped允许8Ring 3 Sandbox禁止只读none禁止2临时环提升Sudo 语义Agent 可申请带 TTL 的临时提权。只有信任分达到目标环阈值才会授权Ring 1 额外要求提供 attestation 字符串Ring 0 永远无法通过标准 API 获取from hypervisor import ExecutionRing, RingElevationManager elevation_mgr RingElevationManager() # 申请临时 Ring 1 权限TTL 默认 300s上限 3600s elevation elevation_mgr.request_elevation( agent_diddid:mesh:agent-1, session_idsession.sso.session_id, current_ringExecutionRing.RING_2_STANDARD, target_ringExecutionRing.RING_1_PRIVILEGED, ttl_seconds300, # 5 分钟后自动过期 attestationsigned-by-sre, # Ring 1 必需 reasondeploy-approval, trust_score0.96, # 或者给 manager 传入 trust_provider ) # 需要时可提前撤销 elevation_mgr.revoke_elevation(elevation.elevation_id) # 周期调用清理已过期提权 elevation_mgr.tick()从 elevation.py 源码可以看到完整的拒绝语义ElevationDenialReason定义了INVALID_TARGET目标环必须比当前环更特权、RING_0_FORBIDDENRing 0 需 SRE Witness 且不可标准申请、INSUFFICIENT_TRUST信任不足、NO_SPONSORSHIPRing 1 缺 attestation、DUPLICATE同会话重复提权等。提权信任阈值也独立配置ELEVATION_TRUST_THRESHOLDS {RING_1: 0.85, RING_2: 0.50}。每次拒绝都会抛出带 remediation 建议的RingElevationError便于 Agent 或操作者理解并修正。此外register_child()实现环继承子 Agent 环级固定为父环降一级数值 1上限 Ring 3。会话配置SessionConfig控制隔离强度、参与者上限与一致性from hypervisor import SessionConfig, ConsistencyMode config SessionConfig( consistency_modeConsistencyMode.STRONG, # 需要共识 max_participants5, max_duration_seconds7200, # 2 小时会话 min_eff_score0.70, # 更高信任门槛 enable_auditTrue, ) session hv.create_session(configconfig, creator_diddid:mesh:admin) hv.activate_session(session.sso.session_id) # 会话生命周期: CREATED - HANDSHAKING - ACTIVE - TERMINATING - ARCHIVEDSessionConfig的__post_init__models.py会严格执行边界校验max_participants必须在 1-1000 之间、max_duration_seconds在 1-604,8007 天之间、min_eff_score在 0.0-1.0 之间越界直接抛ValueError。会话状态机SessionStateCREATED/HANDSHAKING/ACTIVE/TERMINATING/ARCHIVED定义在 models.py。会话隔离的底层是SessionVFSsso.py每个会话一个以/sessions/{session_id}为命名空间的虚拟文件系统支持create/update/delete/permission/restore五类操作的编辑日志最多保留 10,000 条、按路径的权限检查、以及内容哈希/前序哈希追踪为审计引擎提供原始素材。Saga 配置用编程方式定义带补偿的多步事务saga session.saga.create_saga(session.sso.session_id) step session.saga.add_step( saga.saga_id, draft_email, did:mesh:agent-1, execute_api/api/draft, undo_api/api/undo-draft, # 补偿端点 timeout_seconds30, max_retries2, ) result await session.saga.execute_step( saga.saga_id, step.step_id, executordraft_email, ) # 失败时按逆序自动补偿所有已提交步骤Saga 编排器实现在 orchestrator.py超时强制execute_step用asyncio.wait_for包裹执行器超时抛SagaTimeoutError并标记步骤FAILED退避重试总尝试次数为1 max_retries每次重试前await asyncio.sleep(1.0 * (attempt 1))指数退避默认基数为SAGA_DEFAULT_RETRY_DELAY_SECONDS 1.0见 constants.py逆序补偿compensate()遍历saga.committed_steps_reversed对每个已提交步骤调用其undo_api某一步无undo_api或补偿超时/异常时记为COMPENSATION_FAILED若存在失败补偿则 Saga 进入ESCALATED状态并触发Joint Liability联合责任惩罚。从源码可以确认超时语义是协作式取消asyncio.wait_for会先取消再抛错含await点的执行器能收到CancelledError并释放资源纯同步 CPU 任务不会被 Python 取消需要硬终止的调用方应把执行器放到进程/线程池中。Kill SwitchKill Switch 提供优雅的 Agent 终止与 Saga 步骤交接from hypervisor import KillSwitch from hypervisor.security.kill_switch import KillReason kill_switch KillSwitch() # 终止一个行为异常的 Agent result kill_switch.kill( agent_diddid:mesh:rogue-agent, session_idsession.sso.session_id, reasonKillReason.RING_BREACH, ) # result.handoffs —— 被移交给替补 Agent 的在途 Saga 步骤列表 # result.compensation_triggered —— 若 True说明活跃 Saga 被补偿Kill 原因kill_switch.py 的KillReason枚举behavioral_driftAgent 行为偏离预期模式rate_limitAgent 超过限流阈值ring_breachAgent 试图越权访问环级manual操作者手动终止quarantine_timeout隔离期到期仍未解决session_timeout会话超过最大时长实现细节值得强调终止回调在锁外、以DEFAULT_CALLBACK_TIMEOUT_SECONDS 5.0的墙钟超时在守护线程中执行挂死回调不会冻结整个 Kill 流程这正是 Kill Switch 的意义——响应性优先kill 意图会持久记录进_kill_history并体现在返回的KillResult中即使回调失败terminatedFalseAgent 也会被无条件注销需要重试的调用方必须重新注册。限流Rate Limiting按环级自动应用令牌桶限流from hypervisor import AgentRateLimiter from hypervisor.models import ExecutionRing limiter AgentRateLimiter() # 各环默认限额rate tokens/sec, burst capacity # Ring 0 (Root): 100.0 rate, 200.0 capacity # Ring 1 (Privileged): 50.0 rate, 100.0 capacity # Ring 2 (Standard): 20.0 rate, 40.0 capacity # Ring 3 (Sandbox): 5.0 rate, 10.0 capacity # 自定义各环限额 custom_limits { ExecutionRing.RING_0_ROOT: (200.0, 400.0), ExecutionRing.RING_1_PRIVILEGED: (100.0, 200.0), ExecutionRing.RING_2_STANDARD: (30.0, 60.0), ExecutionRing.RING_3_SANDBOX: (2.0, 5.0), } limiter AgentRateLimiter(ring_limitscustom_limits)rate_limiter.py 的实现要点令牌桶以(agent_did, session_id)二元组为键避免 DID 冒号拼接造成的哈希冲突check()超限时抛RateLimitExceededtry_check()则返回Falseupdate_ring()在 Agent 升级/降级时按新环重建满桶桶数量上限默认 100,000超限时逐出最旧桶。限流统计总请求数、拒绝数、可用令牌可通过get_stats()查询。环越权检测Ring Breach Detection越权检测器监控 Agent 的异常访问模式from hypervisor import RingBreachDetector, BreachSeverity detector RingBreachDetector() # 越权事件包含 # severity: NONE | LOW | MEDIUM | HIGH | CRITICAL # anomaly_score: float行为偏离程度 # actual_rate vs expected_rate调用频率异常 # call_count_window检测窗口内的调用次数 # 越权检测触发自动降级或 Kill Switch从文档与测试test_breach_detector.py、test_classifier.py可以确认检测结合滑动窗口速率分析与环距放大ring-distance amplification评估异常并带有熔断器circuit breaker语义。Docker Compose 生产部署Redis 后端状态的生产部署# docker-compose.yml services: redis: image: redis:7-alpine ports: - 6379:6379 hypervisor-api: build: . environment: - REDIS_URLredis://redis:6379/0 - HYPERVISOR_CONFIG/app/config/hypervisor.yaml ports: - 8000:8000 volumes: - ./config:/app/config仓库中还有一份可直接运行的示例编排examples/docker-compose/含 Dockerfile、hypervisor.yaml配置与 sample workflow以及加固沙箱镜像 docker/Dockerfile.sandbox。配置参考表参数类型默认值说明HypervisornexusadapterNone外部信任评分后端policy_checkadapterNone行为验证适配器iatpadapterNone能力清单解析器SessionConfigconsistency_modeConsistencyModeEVENTUALSTRONG共识或EVENTUALgossipmax_participantsint10每会话最大 Agent 数1-1,000max_duration_secondsint3600会话超时1-604,800min_eff_scorefloat0.60加入会话的最低信任分0.0-1.0enable_auditboolTrue启用哈希链审计轨迹Execution RingsRING_0_ROOTint0超管配置与惩罚需 SRE WitnessRING_1_PRIVILEGEDint1不可逆动作eff_score 0.95 共识RING_2_STANDARDint2可逆动作eff_score 0.60RING_3_SANDBOXint3只读/研究默认Ring Elevationttl_secondsint300提权时长上限 3,600sreasonstr提权理由attestationstrNone签名证明Ring 1 必需Saga Stepstimeout_secondsint300步骤超时秒数max_retriesint0最大重试次数execute_apistr必填步骤执行端点undo_apistrNone补偿端点Rate Limitstokens/sec, burstRing 0 (Root)(float, float)(100.0, 200.0)管理操作最高吞吐Ring 1 (Privileged)(float, float)(50.0, 100.0)高信任 Agent 高吞吐Ring 2 (Standard)(float, float)(20.0, 40.0)中等吞吐Ring 3 (Sandbox)(float, float)(5.0, 10.0)受限吞吐Kill SwitchreasonKillReason必填behavioral_drift、rate_limit、ring_breach、manual、quarantine_timeout、session_timeoutBreach DetectionseverityBreachSeverityNONE、LOW、MEDIUM、HIGH、CRITICAL上表中的默认值均可与 constants.py 逐一对应例如RATE_LIMIT_RING_0 (100.0, 200.0)、SAGA_DEFAULT_STEP_TIMEOUT_SECONDS 300、MAX_PARTICIPANTS_LIMIT 1000、MAX_DURATION_LIMIT 604_800是参数解析层与校验层的单一事实来源。架构设计执行环层级环升降级流程降级判定的核心是 enforcer.py 中的should_demote(current_ring, eff_score)当按当前信任分算出的应得环数值大于当前环时即触发降级。注意 Ring 0 对 Agent 永远拒绝——check()中一旦required RING_0_ROOT直接返回requires_sre_witnessTrue的拒绝结果。Saga 生命周期核心特性执行环Execution Rings仿硬件的特权模型Ring 0-3。Agent 依据信任分赢取环级访问权信任下降实时降级带 TTL 的 sudo 提权带熔断器的越权检测。命令黑名单强制RingEnforcer.check_command()会针对全局DENIED_COMMANDS列表校验子进程命令——不区分大小写匹配、剥离;//|等 shell 元字符以防注入绕过见 sandbox/init.py。黑名单覆盖网络抓取工具curl、wget、ftp、telnet、原始套接字/代理工具nc、ncat、socat、nmap、tcpdump、备用解释器perl、ruby、python2、编译器工具链gcc、g、make、cc与各类 shellbash、sh、dash、zsh、ksh、fish。配套的加固镜像还会把这些二进制从文件系统中物理移除PATH 钉扎MINIMAL_SANDBOX_PATH /usr/local/sandbox/bin仅含 python3/python 两个符号链接与文件删除构成纵深防御。Kill Switch优雅终止支持把在途 Saga 步骤交接给替补 Agent按 Agent 按环限流Sandbox 5 rpsRoot 100 rps。无数据丢失地停下失控 Agent。Saga 补偿多步事务具备超时强制、带退避的重试、失败时对已提交步骤的逆序补偿。哈希链审计取证级 delta 轨迹。语义化 diff、哈希链条目、会话结束时返回摘要承诺根哈希。底层是 delta.py 的DeltaEngine每条SemanticDelta记录会话/Agent/时间戳/变更列表与parent_hashcompute_hash()用 SHA-256 对全部字段含父链引用取哈希verify_chain()可整体重放校验哈希正确性与父子链完整性——任何一环被篡改都会导致校验失败。会话终止时由Hypervisor.terminate_session返回链根哈希作为取证摘要。可观测性结构化事件总线为每个动作发出类型化事件带完整委托树编码的因果追踪 ID用于因果一致性的版本计数器。Prometheus 指标收集器跟踪环转换与越权事件prometheus_collector.pyOpenTelemetry span 导出器实现 Saga 到 span 的映射与分布式追踪上下文saga_span_exporter.py。会话隔离共享会话对象SSO 每会话虚拟文件系统 快照 向量时钟因果排序vector_clock.py。DID 绑定身份保证失控 Agent 无法污染其他会话。会话一致性深入细节版本计数器共享 VFS 状态的因果一致性资源锁READ/WRITE/EXCLUSIVE带锁超时隔离级别每个 Saga 可指定 SNAPSHOT、READ_COMMITTED、SERIALIZABLE。基准测试针对环计算、delta 审计捕获、会话生命周期与 Saga 执行的微基准位于 benchmarks/ 目录cd agent-governance-python/agent-hypervisor python benchmarks/bench_hypervisor.py模块地图模块说明hypervisor.session共享会话对象生命周期与 VFShypervisor.rings4 环特权、提权与越权检测hypervisor.reversibilityExecute/Undo API 注册表hypervisor.sagaSaga 编排器与补偿hypervisor.auditdelta 引擎与哈希链审计轨迹hypervisor.verificationDID 交易历史验证hypervisor.observability事件总线、因果追踪 ID、指标hypervisor.security限流器与 Kill Switchhypervisor.integrationsNexus、Verification、IATP 跨模块适配器动作可逆性与环级要求的对应关系定义在 models.py 的ActionDescriptor.required_ringis_admin动作要求 Ring 0不可逆且非只读要求 Ring 1只读动作只需 Ring 3Sandbox其余落在 Ring 2。可逆性等级ReversibilityLevelFULL/PARTIAL/NONE还对应风险权重区间0.1-0.3 / 0.5-0.8 / 0.9-1.0供风险量化使用。测试套件cd agent-governance-python/agent-hypervisor # 运行全部测试 pytest tests/ -v # 仅运行集成测试 pytest tests/integration/ -v # 运行基准 python benchmarks/bench_hypervisor.py仓库测试覆盖了完整功能面单元测试包括 test_rings.py、test_saga.py、test_audit.py、test_command_denylist.py、test_ring_enforcement.py、test_config_validation.py集成测试 test_hypervisor_e2e.py 与 test_scenarios.py 验证端到端场景另有规格一致性测试 test_spec_hypervisor_conformance.py 与沙箱 PATH 冒烟测试 test_sandbox_path.py。REST API运行 FastAPI 服务并打开交互式 Swagger 文档uvicorn hypervisor.api.server:app # 打开 http://localhost:8000/docs 查看 Swagger UI端点组与 server.py 中的路由装饰器一一对应分组端点HealthGET /health、GET /api/v1/statsSessionscreate、list、inspect、join、activate、terminateRingssession distribution、agent ring lookup、access checkSagascreate、list、inspect、add step、execute stepEventsquery events、event statisticsVerificationverify history、clear verification cache可视化 Dashboard交互式 Streamlit 仪表盘cd agent-governance-python/agent-hypervisor/examples/dashboard pip install -r requirements.txt streamlit run app.py标签页Session Overview | Execution Rings | Saga Orchestration | Event Stream。生态定位Agent Hypervisor 是 Agent Governance Ecosystem 的运行时治理组件与以下组件协作Agent OSagent-os策略执行内核向 Hypervisor 提供策略Agent Meshagent-mesh加密信任网络向 Hypervisor 提供信任分Agent SREagent-sreSLO、混沌与成本护栏与 Hypervisor 交换 SLO/混沌信号Agent Hypervisor会话隔离与治理运行时。DID 交易历史验证、Nexus 信任评分、IATP 能力清单三类跨模块适配器位于hypervisor.integrations可在 integrations/ 目录查看用法示例。路线图摘自文档季度里程碑Q1 2026v2.0执行环、Saga 编排与共享会话Q2 2026分布式超管多节点、WebSocket 实时仪表盘、Redis 后端会话Q3 2026自动扩缩环策略的 Kubernetes Operator、CNCF Sandbox 申请Q4 2026v3.0联邦超管网格、跨组织 Agent 治理与 SOC2 证明常见问题为什么 AI Agent 需要 hypervisor就像 OS 超管隔离虚拟机并强制资源边界一样Agent Hypervisor 隔离 AI Agent 会话并强制治理边界。没有隔离共享会话中的一个失控 Agent 就能污染状态、提权或让故障级联扩散到整个系统。执行环与传统访问控制有何不同传统访问控制是静态且二元的允许/拒绝。执行环是动态且分级的Agent 依据信任分赢取环级特权可申请带 TTL 的临时提权类似sudo信任下降时自动降级。环越权检测在损害发生前捕获异常行为。多 Agent Saga 失败会发生什么Saga 编排器对所有已提交步骤触发逆序补偿。每个步骤定义undo_api补偿端点超时步骤会被取消并按max_retries重试随后才执行补偿。总结Agent Hypervisor 的核心价值在于把操作系统层面的进程隔离 特权环 看门狗 审计思想整体移植到 AI Agent 运行时信任分驱动执行环的自动分配与实时降级、TTL 提权模拟 sudo 语义、Saga 补偿让失败的多步工作流自我撤销、Kill Switch 保证失控 Agent 无数据丢失地被终止、SHA-256 哈希链让每步操作都可取证。其实现全部落在 agent-hypervisor/src/hypervisor 的 9 个模块中参数与阈值统一收口于 constants.py配合 30 测试文件与 benchmarks既可作为生产治理参考实现也可作为深入学习 Agent 运行时安全的完整教材。【免费下载链接】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），仅供参考
