Agent Runtime Governance：Agent 工具执行治理 SDK

## 项目背景 Agent 框架通常能完成规划、工具选择和调用编排，但真正触碰文件、数据库、支付接口或基础设施时，仍存在两个关键缺口：审批时确认的动作可能在执行前发生参数或治理状态漂移；网络超时等情况又可能让外部副作用处于未知状态，盲目重试会造成重复删除、重复支付或重复写入。 Agent Runtime Governance 是一个嵌入现有 Agent 技术栈的轻量 Python SDK。它不替代 LangGraph、OpenAI Agents SDK 等框架，而是在工具调用即将产生真实副作用的最终执行边界，统一完成动作绑定、策略判断、审批、身份校验、幂等控制、结果对账、审计和证据生成。 ## 核心架构 运行时以不可变执行上下文为基础，将一次工具调用依次送入规则与策略判断、人工审批、身份和前置条件验证、执行控制、审计与证据层。副作用工具可以声明 `ActionContract`，运行时据此生成 `BoundAction`，把工具名称、冻结参数、调用者身份、租户、策略、风险和外部前置条件绑定到同一个版本化动作摘要。 最终进入工具体之前，运行时会再次校验动作摘要及其依赖的身份、策略、密钥和前置条件。审批后参数被替换、策略版本漂移、身份发行方变化或前置条件失效时，调用会在真实工具执行前失败关闭，从而保证“被批准的动作就是实际执行的动作”。 ## 幂等执行与 UNKNOWN 对账 对于变更型工具，SDK 提供内存与 SQLite 幂等存储、租约续期、参数指纹冲突检测和结果复用。超时或取消并不被简单等同为失败：当外部结果无法确定时，执行状态会记录为 `UNKNOWN`，并保持幂等占用，阻止运行时自动重复副作用。 v0.7 引入持久化 UNKNOWN 对账协议。幂等所有权和最小恢复描述符在副作用分发前原子提交；后续探针、人工处置和状态转移进入仅追加、带修订检查的账本，并通过事务性审计发件箱交付证据。该设计不虚构跨系统 exactly-once，只有下游收据、幂等键或可靠探针能够证明结果时才确认最终状态。 ## 可验证证据与策略决定说明 v0.8 增加隐私安全的 Evidence Bundle，将动作、伪匿名身份、策略、审批、执行状态、对账谱系、审计锚点和脱敏承诺绑定到可移植摘要。可选 Ed25519 签名、封闭信任根、外部收据验证和离线校验命令分别证明完整性、真实性与外部结果，不把普通日志包装成合规证明。 v0.9 在既有动作和证据协议之外增加独立的策略决定说明附件，记录确定性的控制项结果，并支持离线验证、只读比较和轻量 inspect 呈现。附件不保存原始参数、提示词、模型输出或思维链，重点回答“为什么这次动作被允许或拒绝”，同时避免扩大敏感数据面。 ## 框架接入与运行时扩展 SDK 核心保持框架无关，并对独立 Runtime、LangGraph 和 OpenAI Agents SDK 的真实工具入口进行一致性验证。扩展边界支持同步与异步策略、人工决策、审计、快照、身份、OPA、Slack、OpenTelemetry 和 Prometheus；异步优先调度、独立容量限制和受控关闭确保超时或取消后的后台工作不会被误报为已经结束。 ## 工程与发布保障 项目通过 Python 多版本矩阵、Windows 专用测试、属性测试、并发与故障测试、Docker 服务集成、CodeQL、依赖审计和性能预算验证关键边界。正式发布包含 wheel、sdist、SBOM、发布验证清单和供应链证明，并在公共 PyPI 的全新环境中复验安装结果。 当前稳定能力聚焦单进程及单主机 SQLite 持久化场景。多实例 PostgreSQL 权威状态和受限 Redis 协调属于后续独立里程碑，尚未作为现有版本能力宣传。 ## 适用场景 - 需要人工审批的文件、数据库、支付和基础设施变更； - 不能在超时后直接重试的非幂等外部调用； - 需要将策略、身份、审批和实际执行动作绑定的 Agent 系统； - 需要离线验证审计证据、对账谱系或策略决定依据的生产环境。

• 动作契约与最终执行边界
• 审批、身份、策略和参数不可变绑定
• 幂等执行与 UNKNOWN 对账
• 隐私安全 Evidence Bundle 与离线验证
• 可验证策略决定说明
• LangGraph 与 OpenAI Agents SDK 一致性
• 异步优先扩展调度
• CI、安全、性能和供应链发布证据