(課程影片與縮圖將由 Microsoft 內容團隊於合併後新增,符合第 14 / 15 課模式。)
本課將涵蓋:
完成本課後,您將能夠:
想像您在 Contoso Travel 部署了 AI 代理。該代理閱讀客戶請求,呼叫航班 API 查詢方案,並代客訂票。上一季,該代理處理了 5 萬筆訂位。
今日一位稽核人員來到,問了一個簡單的問題:「請給我看你的代理做了什麼。」
您交出日誌檔案。稽核人員看過後問了更難的問題:「我怎麼知道這些日誌沒有被篡改?」
這就是稽核軌跡問題。當前多數代理部署依賴:
若不信任任何人(您、雲端提供者、資料庫商),以上都無法回答稽核人問題。內部使用此信任常可接受,但對受管制工作負載(金融、醫療、受 EU 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.js 版的憑證簽署與離線驗證實作,用於將任何 MCP 伺服器包裝成具竄改證據的審計軌跡,包括保留共簽流程,其中暫停的行動會發出綁定動作摘要的核准憑證(桌面流程借助 WebAuthn),就是前述人類授權筆記本的同一核准憑證模式。pip install nobulex)在 Python 中提供相同 Ed25519 + JCS 簽署模式,搭配 LangChain 與 CrewAI 整合,含公開的跨驗證測試向量及由 OWASP PR #2210 貢獻的合規對映表。
- EMILIA Protocol 提供一個互補的精確動作執行層:離線可驗證的批准收據、綁定的 WebAuthn 或法定人數授權、在執行器邊界一次性消耗,以及一條明確的未決結果路徑。其框架適配器將收據視為必要的證據,而非外部效果已發生的證明。自行開發與使用函式庫的抉擇如同自行撰寫 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 雜湊合併(以確定性的順序串接),並將所得摘要嵌入第三張收據的一個新欄位後簽名。驗證三張收據仍可相互通過驗證。你剛完成了一階包含證明:持有第三張收據的人可以證明前兩張收據在簽名時存在,無需揭露其內容。這是選擇性披露收據在大規模使用的模式(梅克爾承諾,RFC 6962)。
密碼學收據為 AI 代理提供以下審計軌跡:
它們並不能取代輸入驗證、政策執行、執行者的準入、 結果證據、完整性控制,或身份基礎設施。它們是這些層的基礎 在受監管或跨多組織的工作流程中,收據使特定的 發行者的聲明能夠在審計者自己的信任配置下被獨立檢核。
最重要的重點:收據證明某個特定的金鑰簽署了特定的 內容。隨附的時間戳記是簽署者的一項聲明,除非另有獨立的時間見證。 收據並不證明其內容為真、某項動作已執行,或該 記錄集是完整的。務必嚴格區分這些不同點。
當你準備從本課程畢業並在真實環境部署收據簽署代理時:
加入 Microsoft Foundry Discord,與其他學習者會面,參加辦公時間,並獲取你的 AI 代理問題回答。
本課程涵蓋單張收據簽署與雜湊鏈序列。相同原語可構成若干高階模式,隨著你的治理態勢成熟,你可能會遇到:
authorization_*)與執行後(result_*)兩半,各自簽名,適用於授權決策與實際結果由不同角色或時間點產生的狀況。此架構可加成於本課程教授的格式。result_hash 的任何位元組。實務載荷往往比單一工具調用結果更豐富:預決策推理(模型預測、考慮選項、證據及其完整性、風險態勢、問責鏈、門控結果)皆可納入載荷,由單一收據封存。保持收據格式精簡,同時讓載荷結構可依領域發展。alg 標籤並不等同於遷移:一個設定檔必須定義 ML-DSA 金鑰編碼、規範化的簽署位元組、驗證、依賴方策略、降級抗性,以及過渡語義。作出相容性聲明之前,應針對共享向量規劃並測試雙重簽名過渡。免責聲明: 本文件由 AI 翻譯服務 Co-op Translator 翻譯而成。雖然我們致力於確保準確性,但請注意,機器自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊,建議進行專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤釋承擔責任。