智能体决策回执

agent-decision-receipts
分类通用
作者Alireza Rezvani
许可MIT
评分4.60/5
使用5.5K

智能体决策凭据 (Agent Decision Receipts)

概述

日志记录的是操作“发生了”。而凭据（receipt）具有防篡改特性：它记录了执行者、操作内容及遵循的策略，并经过签名，因此任何后续修改都会导致签名失效。本技能可为具有重大影响的智能体操作铸造凭据，并支持后续仅凭证书进行验证：无需数据库，无需网络，无需信任发行方。

加密实现不在本技能内部，而是采用开源的 OpenAgentOntology 凭据原语（Apache-2.0）。它使用 Ed25519 对每个凭据进行签名；若安装了后量子后端，还会增加 ML-DSA-65 (FIPS 204) + SLH-DSA (FIPS 205) 的后量子签名。本技能处于决策层：决定何时铸造、写入内容以及如何验证。一次安装，无需为每个技能单独配置加密。

仅包含三个决策环节：

1. 此操作是否需要凭据？ —— 具有副作用 + 影响重大 + 需事后可证明 = 是。
2. 铸造凭据 —— 构建操作清单（action manifest），使用 OAO 原语进行签名。
3. 验证凭据 —— 仅凭证书重新计算哈希并检查每个签名分支。

本技能不是日志分析。日志描述发生了什么，且可以被静默修改。凭据在执行前/执行时铸造，一旦修改即失效。调试请使用日志，取证请使用凭据。

本技能不是托管公证服务。它铸造的是一个本地的、自签名的凭据，任何人都可以离线验证。跨组织验证（一个组织向另一个组织证明）属于独立的托管服务，不在本范围之内。

本技能不是法律意见。它生成的是旨在支持 FRE 902(13)/(14) 风格认证和《欧盟 AI 法案》第 12 条记录保存的证据。具体凭据是否被采信需咨询法律顾问。

快速上手

bash
# 安装开源凭据原语 (Apache-2.0)。添加 [pq] 以支持后量子签名。
pip install "openagentontology[pq]"

1. 构建并验证操作清单 (仅限标准库，无加密，无网络)

python scripts/build_action_manifest.py --agent my-deploy-agent --operation deploy \
    --target prod/api --policy "EU AI Act Art 12" --out action.json

2. 为其铸造凭据 (Ed25519 + 后量子签名)

python -c "import json,openagentontology.receipt as r; \
  print(json.dumps(r.mint_receipt(json.load(open('action.json')), decision='ACTION_GOVERNED')))" > receipt.json

3. 仅凭证书验证 (无需数据库，无需网络)

python -c "import json,openagentontology.receipt as r; \
  print(r.verify_receipt(json.load(open('receipt.json'))))"

-> {'ok': True, 'sig_ok': True, ... 'reason': 'verified from the cert alone via: ed25519, ml_dsa, slh_dsa'}

> 依赖说明：本技能将签名委托给 openagentontology (Apache-2.0, 通过 pip install 可选安装)。此处提供的脚本仅使用标准库，不增加仓库依赖；该包由操作员自行安装（BYO-library 模式）。如果未安装，构建步骤仍然有效。
s — 仅在铸造（minting）或验证（verifying）时需要。

核心工作流

以下三个决策是该技能的核心：决定是否记录凭据（receipt）、铸造凭据，然后验证凭据。

决策 1：此操作是否需要凭据？

当操作同时满足以下三个条件时，铸造凭据：

| 测试项 | 满足以下条件则铸造... |
|------|-----------|
| 具有副作用 | 涉及写入、发送、部署、删除、支付、授予权限或更改外部状态 |
| 具有后果性 | 错误的调用会导致金钱损失、违反合规性或对人员造成伤害 |
| 后续可证明 | 审计员、保险公司、监管机构、法院或交易对手可能会询问“代理执行了什么以及原因是什么？” |

只读、可逆或琐碎的操作不需要凭据。全部记录会导致信号被淹没；完全不记录则会导致关键调用无法证明。

高信号触发器（默认铸造）：deploy（部署）、delete（删除）、pay/wire/refund（支付/汇款/退款）、grant_access（授予权限）、export/egress（导出/流出）、approve/deny（批准/拒绝）一项申请，以及高风险 AI 系统中任何影响个人的模型决策。

决策 2：铸造凭据

操作清单（action manifest）是任何描述代理行为的 ASCII 安全字典。必须包含四个键 —— 如果缺失任何一个，build_action_manifest.py 将拒绝该清单（退出码 2）。另外两个键会自动添加：

| 键 | 是否必填 | 承载内容 |
|-----|-----------|-----------------|
| agent_id | 必填 | 执行操作的代理 |
| operation | 必填 | 动词（deploy / delete / pay / decide / ...） |
| target | 必填 | 操作对象 |
| policy | 必填 | 约束该操作的规则（例如 “EU AI Act Art 12”, “内部变更控制”） |
| inputs_hash | 自动添加 | --inputs 的哈希值，因此无需明文存储完整负载（若省略 --inputs，则默认为空值的哈希） |
| decision_label | 自动添加 | 凭据决策标签（默认为 ACTION_GOVERNED） |

mint_receipt(manifest, decision=...) 将完整清单哈希为凭据证据，对规范化主体进行签名，并返回一个包含以下内容的凭据：evidence_hash、signature_b64 (Ed25519)，以及（在安装了 [pq] 的情况下）ml_dsa_signature_b64 + slh_dsa_signature_b64。每个签名分支签署的字节相同；任何一个通过验证即可证明真实性。

> 完整凭据架构和后量子算法原理请参阅 references/receipt-fields.md。

决策 3：验证凭据

verify_receipt(receipt) 重新计算 sha256(canonical(evidence))，将其与 evidence_hash 进行比较，然后检查其拥有后端的每个签名分支。它返回 {ok, hash_ok, sig_ok, legs, reason}。操作中任何一个字节的篡改都会导致 hash_ok 失效；伪造的签名会导致相应分支失效。验证仅需要凭据本身 —— 无需回调发行方。

正是这一特性使其成为“证据”：即使审核员不信任发行方，仍然可以完全离线地确认凭据的完整性和真实性。

反模式

  • 记录日志而非决策。 对事后写入的日志行铸造凭据不能证明任何事情。应在操作发生的时刻，针对操作本身进行铸造。
  • 将签名密钥与凭据存储在一起。 如果密钥泄露，签名将毫无意义。将密钥视为任何签名密钥一样对待；绝不要将其提交到代码库。
  • 在可用后量子分支时仅使用 Ed25519。 凭据是长期有效的证据。请使用后量子分支（ML-DSA-65 + SLH-DSA）进行签名，以便在未来量子计算机能够破解 Ed25519 时，凭据依然可验证。请安装 [pq]。
  • 放入原始密钥或个人隐私信息（PII）...
  • 清单内容：清单被哈希到证据中，并可通过收据恢复。传输哈希值（inputs_hash）而非明文。
  • 避免称其为“可采纳的”：它旨在提供*支持* FRE 902(13)/(14) 风格认证的证据。可采纳性由法院决定，而非由工具主张。
  • 在缺失加密时伪造签名：原语应发出明确的 unsigned 标志。绝不能将未签名的收据呈现为已签名。

交叉引用

  • ra-qm-team/skills/eu-ai-act-specialist/ —— 确定 AI 系统的风险等级和第 12 条义务；该技能可铸造这些义务所要求的单次操作记录。
  • ra-qm-team/skills/iso42001-specialist/ —— AI 管理系统控制项；收据是这些控制项所要求的单次决策证据。
  • OpenAgentOntology (Apache-2.0)：该技能驱动的开放收据原语 —— pip install "openagentontology[pq]"。