(课程视频和缩略图将在合并后由微软内容团队添加,遵循第14 / 15课的模式。)
本课将涵盖:
完成本课后,您将了解如何:
假设您已为 Contoso Travel 部署了一个 AI 代理。该代理读取客户请求,调用航班 API 查找选项,并代表客户预订座位。上个季度,该代理处理了5万个预订。
今天一位审计员来了。他们提出一个简单的问题:“告诉我代理做了什么。”
您交出日志文件。审计员查看后提出更难的问题:“我怎么知道这些日志没有被篡改?”
这就是审计轨迹的问题。当前大多数代理部署依赖于:
这些都无法在不要求审计员信任某人的情况下回答问题(您、您的云服务提供商或数据库供应商)。对于内部使用,这种信任通常可以接受。对于受监管的工作负载(金融、医疗、受欧盟AI法案约束的任何内容),则不行。
加密收据通过使签名声明能够独立地 可验证。审计员仍然需要一个带外的理由来信任签名密钥和 生成该声明的组件。嵌入式密钥证明自洽性, 而不是发行者身份或强制执行的位置。
收据是一个JSON对象,记录代理所做的事情,并带有数字签名。
flowchart LR
A[Agent invokes a tool] --> B[Build receipt payload]
B --> C[Canonicalize JSON RFC 8785]
C --> E[Ed25519 sign canonical bytes]
E --> F[Receipt with signature]
F --> G[Auditor verifies offline]
G --> H{Signature valid?}
H -- yes --> I[Signed statement is intact]
H -- no --> J[Receipt rejected]
一个最简收据如下:
{
"type": "agent.tool_call.v1",
"agent_id": "contoso-travel-bot",
"tool_name": "lookup_flights",
"tool_args_hash": "sha256:a3f9c1...",
"result_hash": "sha256:7b2e1d...",
"policy_id": "contoso-travel-policy-v3",
"timestamp": "2026-04-25T14:30:00Z",
"sequence": 47,
"previous_receipt_hash": "sha256:9d4e6a...",
"signature": {
"alg": "EdDSA",
"sig": "c5af83...",
"public_key": "8f3b2c..."
}
}
三个属性起作用:
签名。收据由代理的网关使用 Ed25519 私钥签名。任何拥有相应公钥的人都可以离线验证该签名。依赖方必须固定该密钥或从收据外的受信任注册表解析它。篡改任何已签名字段都会使签名失效。
规范编码。签名前,收据使用 JSON 规范化方案(JCS,RFC 8785)序列化。这确保两个实现只要逻辑收据相同,生成的字节输出就完全相同。没有规范化,不同的 JSON 序列化器会为相同内容生成不同签名。
哈希链. previous_receipt_hash 字段将每个收据与其前一个收据链接起来. 删除或重新排序某个收据会破坏所呈现的序列. 检测截断或签名者控制的重写还需要一个固定的当前链头, 独立见证的检查点, 或经过认证的封闭群体承诺.
这些属性共同提供三个保证:
生成收据不需要特殊库。加密原语广泛可用,逻辑只需几十行 Python 代码。
在 code_samples/18-signed-receipts.ipynb 中的动手练习演示了整个流程。受版本控制的 code_samples/18-signed-receipts.execution-receipt.json 记录了最新一次干净执行的确切笔记本哈希、Python 环境、单元格数量和检查结果,并且不会更改课程已保存的输出。总结版本:
import json
import hashlib
import base64
from nacl import signing
from jcs import canonicalize # RFC 8785 canonical JSON
def b64url_nopad(data: bytes) -> str:
return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
def sha256_canonical(obj) -> str:
"""SHA-256 of a Python object's JCS-canonical JSON form."""
return f"sha256:{hashlib.sha256(canonicalize(obj)).hexdigest()}"
# Generate or load a signing key (in production, store in a key vault)
signing_key = signing.SigningKey.generate()
verify_key = signing_key.verify_key
TRUSTED_PUBLIC_KEYS = {b64url_nopad(bytes(verify_key))} # pinned out of band by the verifier
# Build the receipt payload (no signature yet)
tool_args = {"origin": "SYD", "destination": "LAX"}
tool_result = [{"flight": "QF11", "price": 1850, "stops": 0}]
payload = {
"type": "agent.tool_call.v1",
"agent_id": "contoso-travel-bot",
"tool_name": "lookup_flights",
"tool_args_hash": sha256_canonical(tool_args),
"result_hash": sha256_canonical(tool_result),
"policy_id": "contoso-travel-policy-v3",
"timestamp": "2026-04-25T14:30:00Z",
"sequence": 0,
"previous_receipt_hash": None,
}
# Canonicalize and sign the JCS bytes directly. PureEdDSA hashes internally.
canonical_bytes = canonicalize(payload)
signature_bytes = signing_key.sign(canonical_bytes).signature
# Attach a structured signature object.
receipt = {
**payload,
"signature": {
"alg": "EdDSA",
"sig": b64url_nopad(signature_bytes),
"public_key": b64url_nopad(bytes(verify_key)),
},
}
这就是整个签名流程。笔记本中的练习详细讲解每个步骤。
验证是逆向操作:
import base64
import hashlib
from nacl import signing
from nacl.exceptions import CryptoError
from jcs import canonicalize
def b64url_decode(s: str) -> bytes:
padding = "=" * ((4 - len(s) % 4) % 4)
return base64.b64decode(s + padding, altchars=b"-_", validate=True)
def verify_receipt(receipt: dict, trusted_public_keys: set[str]) -> bool:
# The signature is a structured object: {"alg", "sig", "public_key"}.
if not isinstance(receipt, dict):
return False
sig_obj = receipt.get("signature")
if not isinstance(sig_obj, dict) or sig_obj.get("alg") != "EdDSA":
return False
try:
# An inline key proves only self-consistency. Trust is configured out of band.
public_key = sig_obj.get("public_key")
signature = sig_obj.get("sig")
if not isinstance(public_key, str) or not isinstance(signature, str):
return False
if public_key not in trusted_public_keys:
return False
payload = {k: v for k, v in receipt.items() if k != "signature"}
canonical_bytes = canonicalize(payload)
verify_key = signing.VerifyKey(b64url_decode(public_key))
verify_key.verify(canonical_bytes, b64url_decode(signature))
return True
except (CryptoError, TypeError, ValueError, KeyError, OverflowError):
return False
该函数接收一个收据以及依赖方已固定的密钥集并返回
True 仅当签名在被接受的密钥下有效时才返回。验证不需要
网络调用,但密钥信任仍然是一个外部配置决定。
为了展示篡改检测,笔记本演示了:
tool_args_hash字段的一个字节。这是收据防篡改的实际证明:任何修改,无论多小,都破坏签名。
单个签名收据保护一次行动。收据链保护一系列行动。
flowchart LR
R0[Receipt 0<br/>genesis] --> R1[Receipt 1]
R1 --> R2[Receipt 2]
R2 --> R3[Receipt 3]
R1 -. previous_receipt_hash .-> R0
R2 -. previous_receipt_hash .-> R1
R3 -. previous_receipt_hash .-> R2
每个收据记录前一个收据的哈希。要悄无声息地删除收据2,攻击者需要:
previous_receipt_hash字段(破坏收据3的签名),或者如果私钥受到保护并且验证者固定了一个独立见证的链 头,这些攻击是可检测的。在每个收据中发布该密钥并不 足够:签名者或攻击者可以出示不同的密钥、改写一个后缀,或 截断该链,除非依赖方具有外部信任与完整性锚点。
笔记本演示了:
previous_receipt_hash是否匹配前一个收据的实际哈希。这是你生成审计轨迹的方式,外部审计员可以在其 自己固定的颁发者密钥和链检查点下验证,而无需信任你可变的日志存储。
这是本课最重要的部分。收据功能强大,但其能力有限。
收据可以证明三件事:
收据不能证明:
policy_id引用的政策是否真的评估过,或者如果检查过会否批准此行为。收据记录的是所声称的内容,而非执行的强制内容。这个边界重要原因有二:
常见误区是认为“有收据”即意味着“已治理”。并非如此。收据是基础,治理是你在此基础上构建的系统。
上文的第 3 条值得单独作为一节:操作收据说明 “此密钥对该内容进行了签名,” 而不是 “某个人授权了此操作.” 对于高风险操作 (退款、删除、银行电汇),单独的审批人签名可以绑定确切的操作。将该密钥与某个人关联并检查该人的在场性仍然是独立的责任。
后续的笔记本 code_samples/human-authorization-receipts.ipynb 添加了第二种收据类型,human.approval.v1,采用与课程的收据相同的信封形状。 该信封包含一个类型化的有效载荷,该有效载荷使用 Ed25519 对其规范化的 JCS 字节进行签名,signature 对象位于签名字节之外。 批准者密钥对 完整的规范化操作及其摘要 进行签名;代理者密钥对一个声明进行签名,该声明携带 相同的操作摘要 以及一个 parent_approval_ref,即批准的 receipt_hash,采用与您在上面构建的链中 previous_receipt_hash 相同的约定。 一个 verify_chain 在 各自的已固定密钥注册表 下遍历两个工件。 批准者密钥和代理密钥保持分离,因此代码路径是共享的,但授权方永远不会共享。
这一性质带来的保证,谨慎表述为:固定的批准者密钥签署了这个确切的 操作,且代理密钥随后签署了一份携带相同操作摘要的声明。 这是有用的证据,但它本身并不能证明该操作已被执行。要 控制执行,确切的批准还必须在 实际执行者边界上被保留并消费一次;未知的提供者结果必须保持未知,而不是被 盲目重试。笔记本的拒绝夹具测试收据链层:
每次失败都会以不同的理由拒绝,因此审计员在阅读拒绝时可以判断是授权已失效还是所声称的操作发生了变化。验证是只读且可重复的:它不会消耗批准或调用提供者。单独的执行者需要持久的、原子性的重放保护以及明确的成功、失败和不确定的结果。人类批准收据是本课程定义的一种教学性组合,而不是 draft-farley-acta-signed-receipts 定义的收据类型。
本课中的 Python 代码故意写得极简,方便你逐行阅读并完全理解。生产环境中,你有两个选择:
直接基于加密原语构建。 你刚才看到的50行代码已适用于许多场景。PyNaCl(Ed25519)和jcs包(规范化 JSON)是维护良好且已审计的库。
使用生产用收据库。 若干开源项目实现了相同模式并加添附加功能(密钥轮换、批量验证、JWK 集分发、与策略引擎整合):
draft-farley-acta-signed-receipts,修订02)中的 JCS 与签名作用域约定。本课的扁平教学收据与该草案的 {payload, signature} 包封格式不同,不应视为其合规实现。该草案发布了共享合规套件(agent-governance-testvectors),供以其线格式为目标的实现使用。protect-mcp (npm)和 @veritasacta/verify (npm)包提供了基于 Node 的收据签名及离线验证实现,可包装任何 MCP 服务器生成防篡改审计链,包括支持的共签流程——暂停操作发出绑定操作摘要的批准收据(桌面流程中基于 WebAuthn),与上述人类授权笔记本采用的批准收据方案相同。pip install nobulex)在 Python 中实现相同的 Ed25519 + JCS 签名模式,集成了 LangChain 和 CrewAI,包含发布的交叉验证测试向量,并通过 OWASP PR #2210 提供合规映射。
- EMILIA 协议 提供了一个互补的精确动作强制层:离线可验证的批准收据、绑定的 WebAuthn 或法定人数(quorum)授权、在执行器边界的一次性消费,以及一个明确的不确定结果路径。其框架适配器将收据视为必要的证据,而不是外部效果已发生的证明。选择自写还是用库,与选择自写 JWT 库或用测试库类似:两者合理;库节省时间,减少审计面;自写需理解每个原语。本课教授自写路径,奠定任一选择的基础。
在进入练习之前测试理解。
1. 收据用代理的 Ed25519 私钥签署。审计员只有公钥,能否离线验证收据?
2. 攻击者修改收据的policy_id字段,声称它受更宽松政策管辖。签名覆盖的是原始负载。验证时会怎样?
3. 为什么收据包含 tool_args_hash 和 result_hash,而不是原始参数和结果?
4. previous_receipt_hash 字段将每个收据与其前驱链接。如果攻击者悄悄删除链中间的一个收据,会导致什么无效?
5. 收据验证通过。这能证明代理的行为是正确、合理或符合政策吗?
打开 code_samples/18-signed-receipts.ipynb 并完成所有四个部分:
扩展挑战1: 扩展收据模式,新增你选择的字段(例如,用于追踪的请求 ID),更新规范签名逻辑以包含该字段,并确认收据仍可通过验证。然后在签名后修改该字段,确认验证失败。此练习迫使你理解规范编码的每一个字节如何影响签名。
扩展挑战2: 对你的两个收据的规范字节进行 SHA-256 哈希(按确定顺序连接),并将结果摘要作为第三个收据的新字段嵌入,然后签名。验证这三个收据均可完整回环。你刚刚构建了一个一步包含证明:任何持有第三个收据的人都能证明前两个收据在签名时存在,而无需暴露它们的内容。这是规模化选择性披露收据(Merkle 承诺,RFC 6962)使用的模式。
密码学收据为 AI 代理提供了一个审计轨迹,它是:
它们不能替代输入验证、策略执行、执行者准入, 结果证据、完整性控制或身份基础设施。它们是一个基础 用于那些层。在受监管或多组织的工作流程中,收据使特定 发行者声明可以在审计员自己的信任配置下独立核查。
最重要的要点:收据证明特定密钥对特定 内容。随附的时间戳是签署者的断言,除非另行经时间见证。 收据并不证明其内容为真、某项操作已执行,或 记录集是完整的。务必严格区分这些概念。
准备好从本课毕业,部署签收据的代理于真实环境时:
加入 Microsoft Foundry Discord,与其他学习者会面,参加办公时间,获取你的 AI 代理问题的答案。
本课涵盖单一收据签名和哈希链序列。以下更高级模式也是成熟治理姿态中常见的组合:
authorization_*)和执行后(result_*)两半并分别签名,适用于授权决策和观察结果由不同实体或在不同时间生成的情况。该模式可叠加于本课所示的收据格式之上。result_hash 的任意字节。现实负载通常比单次工具调用结果更丰富:决策前的推理(模型预测、考虑选项、证据及其完整性、风险态势、责任链、门控结果)都可以包含其中,由单一收据封装。这样保持收据格式极简,同时允许按领域演进负载模式。alg 标签并不构成迁移:配置文件必须定义 ML-DSA 密钥编码、规范签名字节、验证、依赖方策略、防降级能力和迁移语义。在声称兼容性之前,应针对共享向量对双重签名迁移进行规划和测试。免责声明: 本文件由 AI 翻译服务 Co-op Translator 翻译完成。尽管我们力求准确,但请注意,自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息,建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。