mirrors / microsoft--ai-agents-for-beginners

项目文件夹

microsoft--ai-agents-for-beginners
文件
main
T
wehub-resource-sync c79da9cdf9 chore: import upstream snapshot with attribution
2026-07-13 12:59:43 +08:00

21 KiB
原始文件 永久链接 Blame 文件历史

觀看課程視頻：使用加密收執保障 AI 代理

(課程視頻及縮圖將由 Microsoft 內容團隊在合併後添加，符合第 14 / 15 課的模式。)

使用加密收執保障 AI 代理

簡介

本課程將涵蓋：

  • AI 代理審計軌跡為合規、除錯與信任重要的原因。
  • 什麼是加密收執，以及它如何不同於未簽名的日誌行。
  • 如何用純 Python 產生代理工具呼叫的簽名收執。
  • 如何離線驗證收執及偵測篡改。
  • 如何鏈接收執以致刪除或重新排序其中一筆會破壞整條鏈。
  • 收執能證明什麼，及明確不證明什麼。

學習目標

完成本課程後，您將會知道如何：

  • 識別促使代理行動加密來源的失效模式。
  • 對標準化 JSON 載荷產生 Ed25519 簽名收執。
  • 僅使用簽署者的公鑰獨立驗證收執。
  • 透過重新驗證被修改的收執來偵測篡改。
  • 建立收執的雜湊鏈序列並說明鏈條重要性。
  • 辨明收執所證明（歸屬、完整性、排序）與不證明（行動正確性、政策正確性）之間的界限。

問題：您的代理審計軌跡

想像您為 Contoso Travel 部署了一個 AI 代理。該代理讀取客戶要求，呼叫航班 API 查詢選項，並代表客戶預訂座位。上個季度，該代理處理了 50,000 筆訂位。

今天來了一位稽核員。他們問一個簡單問題：「給我看您的代理做了什麼。」

您交出日誌檔案。稽核員閱讀後問更難的問題：「我怎麼知道這些日誌沒有被修改？」

這就是審計軌跡問題。當前多數代理部署依賴：

  • 應用程式日誌：由代理自身撰寫，任何有檔案系統存取權者可修改。
  • 雲端日誌服務：平台層面防篡改但需稽核員信任平台營運者。
  • 資料庫交易日誌：適合資料庫變更，不適用於任意工具呼叫。

這些方法皆需稽核員信任某人（您、您的雲端供應商、您的資料庫廠商），對於內部使用通常可接受，但對監管工作負載（金融、醫療、受歐盟 AI 法規約束者）則不行。

加密收執藉由讓每個代理行動可獨立驗證解決了這個問題。稽核員不需信任您，只需有您的公鑰和收執本身。

什麼是加密收執？

收執是一個 JSON 物件，錄製代理所做的事，並以數位簽章簽署。

flowchart LR
    A[代理人調用工具] --> B[構建收據有效載荷]
    B --> C[標準化 JSON RFC 8785]
    C --> D[SHA-256 雜湊]
    D --> E[Ed25519 簽名]
    E --> F[帶簽名的收據]
    F --> G[審計員離線驗證]
    G --> H{簽名有效？}
    H -- yes --> I[防篡改證明]
    H -- no --> J[收據被拒絕]

最簡版本的收執如下：

{
  "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..."
  }
}

三個屬性在發揮作用：

  1. 簽名。收執由代理閘道使用 Ed25519 私鑰簽署。任何擁有相對應公鑰者皆可離線驗證簽名。任一欄位被篡改，簽名即不成立。

  2. 標準化編碼。簽署前，收執以 JSON 標準化方案 (JCS, RFC 8785) 序列化。此舉確保不同實作產生相同邏輯收執時，輸出位元組完全相同。若無標準化，不同 JSON 序列化器對相同內容會產生不同簽名。

  3. 雜湊鏈接。previous_receipt_hash 欄位將每條收執串接到前一條。刪除或重新排序收執會破壞後續收執。即使繞過了單筆簽名，鏈條層級仍能見證篡改。

這些屬性合而為一，提供三種保證：

  • 歸屬：此金鑰簽署了此內容。
  • 完整性：內容自簽署後未被更改。
  • 排序：此收執於鏈中在該收執之後。

用 Python 產生收執

不需特殊函式庫即可產生收執。加密基礎構件廣泛可得，邏輯只要幾十行 Python。

code_samples/18-signed-receipts.ipynb 中的實作演練示範完整流程，摘要版本：

import json
import hashlib
import base64
from nacl import signing
from jcs import canonicalize  # RFC 8785 規範化 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()}"

# 產生或載入簽署密鑰（生產環境中，存放於金鑰保管庫）
signing_key = signing.SigningKey.generate()
verify_key = signing_key.verify_key

# 建立收據內容（尚未簽署）
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,
}

# 規範化、雜湊、簽署。
canonical_bytes = canonicalize(payload)
message_hash = hashlib.sha256(canonical_bytes).digest()
signature_bytes = signing_key.sign(message_hash).signature

# 附加結構化簽署物件。
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 BadSignatureError
from jcs import canonicalize

def b64url_decode(s: str) -> bytes:
    padding = "=" * ((4 - len(s) % 4) % 4)
    return base64.urlsafe_b64decode(s + padding)

def verify_receipt(receipt: dict) -> bool:
    # 簽名是一個結構化的物件：{"alg", "sig", "public_key"}。
    sig_obj = receipt.get("signature")
    if not sig_obj or sig_obj.get("alg") != "EdDSA":
        return False

    # 重建實際被簽署的有效載荷（除了簽名之外的所有內容）。
    payload = {k: v for k, v in receipt.items() if k != "signature"}

    canonical_bytes = canonicalize(payload)
    message_hash = hashlib.sha256(canonical_bytes).digest()

    try:
        verify_key = signing.VerifyKey(b64url_decode(sig_obj["public_key"]))
        verify_key.verify(message_hash, b64url_decode(sig_obj["sig"]))
        return True
    except BadSignatureError:
        return False

此函數接收收執，若簽名有效回傳 True，否則回傳 False。無須網路呼叫，無服務依賴，也不需信任任何第三方。

演練中以以下步驟展示篡改偵測：

  1. 產生有效收執並確認驗證通過。
  2. 修改 tool_args_hash 字段的一個 byte。
  3. 重新執行驗證，發現驗證失敗。

這是收執防篡改的實際演示：任何細微修改皆會破壞簽名。

為多步驟代理鏈接收執

單一簽名收執保護單一行動。收執鏈保護行動序列。

flowchart LR
    R0[收據 0<br/>創世] --> R1[收據 1]
    R1 --> R2[收據 2]
    R2 --> R3[收據 3]
    R1 -. previous_receipt_hash .-> R0
    R2 -. previous_receipt_hash .-> R1
    R3 -. previous_receipt_hash .-> R2

每個收執記錄前一收執的雜湊。竊賊若想在鏈中間悄悄刪除收執 2，只能：

  • 修改收執 3 的 previous_receipt_hash 欄位（破壞收執 3 簽名），或
  • 偽造收執 3 的新簽名（需代理私鑰）。

若私鑰存於硬體金鑰保管庫且您與每份收執一同公開公鑰，則不論哪種攻擊皆難以隱藏且會被察覺。

筆記本引導您：

  1. 建立三筆收執鏈。
  2. 驗證每筆收執的 previous_receipt_hash 是否符合前一收執的真正雜湊。
  3. 違法修改中間某筆收執並觀察鏈條於該點中斷。

此即外部稽核員可獨立驗證且不需信任您的審計軌跡建立法。

收執證明了什麼（不證明什麼）

本節是本課程最重要部分。收執強大但力量有限。

收執證明三件事：

  1. 歸屬：指定位金鑰簽署了特定載荷。
  2. 完整性：載荷自簽署後未更動。
  3. 排序：收執在雜湊鏈中於該收執之後。

收執不證明：

  1. 正確性：代理行動是否正確。無論答案正確或錯誤，收執簽署流程相同。
  2. 政策遵循：policy_id 所稱政策是否實際評估過，或即使評估是否允許此行動。收執只記錄宣稱內容，非執行結果。
  3. 超越金鑰的身份：收執表示「此金鑰簽署此內容」，不表示「這個人類授權」。將金鑰映射至個人或組織需獨立身份基建（目錄、公鑰註冊等）。
  4. 輸入真實性：若代理接收到被操控的提示並依此行動，收執忠實記錄行動。收執是輸入驗證的下游，不是替代。

此界限重要因兩點：

  • 清楚告訴您收執的用途：使代理行為可審核且防篡改，甚至跨組織皆然。
  • 指出您仍須的額外層級：輸入驗證（第 6 課）、政策執行（以下簡述）、身份基建（本課不涉）。

常見錯誤是誤認「有收執」即代表「被治理」。事實不然，收執是基礎，治理是您建立其上的系統。

生產環境參考

本課程示範的 Python 程式碼故意簡化，以便您每行都看得懂，了解細節。生產環境有兩種選擇：

  1. 直接基於加密原語建構。 上述 50 行程式碼足以應付多數用途。PyNaCl（Ed25519）及 jcs 套件（標準化 JSON）皆是維護良好且經過審核的函式庫。

  2. 使用生產用收執函式庫。 數個開源專案實作相同模式並增添功能（密鑰輪替、批次驗證、JWK 集合分發、策略引擎整合）：

    • 本課收執格式遵循目前處理標準的 IETF 草案 (draft-farley-acta-signed-receipts)。
    • Microsoft Agent Governance Toolkit 將收執結合 Cedar 政策決策；詳見該專案下教學 33 節的端到端範例。
    • protect-mcp (npm) 與 @veritasacta/verify (npm) 提供 Node 平台的收執簽名及離線驗證適用函式庫，方便給 MCP 伺服器添加防篡改稽核軌跡。
    • nobulex Python SDK (pip install nobulex) 提供同樣的 Ed25519 + JCS 簽名模式，具備 LangChain 及 CrewAI 整合，含已發布的交叉驗證測試向量及經由 OWASP PR #2210 提供的合規對應。

自行實作與函式庫兩者選擇，有如自己寫 JWT 函式庫或使用已有函式庫：均合理，函式庫節省時間並減少審核面向，而自行撰寫強迫您理解每個原語。本課程教您自行撰寫路徑，為任何選擇奠定基礎。

知識測驗

在進行實作前，先測試理解。

1. 收執用代理私鑰 Ed25519 簽署，但稽核員只有公鑰。稽核員能離線驗證收執嗎？

答案

能。Ed25519 驗證只需公鑰與簽署位元組，無須網路呼叫與第三方服務依賴。此特性使收執在隔離、跨組織或低信任稽核環境中有用。

2. 攻擊者修改收執的 policy_id 欄位，宣稱受較寬鬆的政策管轄，但簽名是對原始載荷計算的。驗證會如何？

答案

驗證失敗。簽名是對標準化的原始載荷位元組計算；任何欄位更動都改變標準化結果，進而改變 SHA-256 雜湊值，使簽名無效。攻擊者若無私鑰，無法重新產生有效簽名。

3. 收執為何包 tool_args_hash 和 result_hash，而非原始參數與結果？

答案

兩點原因。第一，收執可能需被存檔或在環境中傳輸，洩漏原始內容（個人識別資訊、商業資料）有問題。雜湊保持收執體積小且內容私密；稽核員驗證雜湊對應獨立存放的實際內容。第二，雜湊大小固定；有雜湊的收執大小受限，不論輸入輸出多大。

4. previous_receipt_hash 將每份收執連結至前一份。若攻擊者在鏈中間悄悄刪除一份收執，什麼失效？

答案

後續每份收執失效。因它們的 previous_receipt_hash 不再匹配實際鏈（因所連結的收執已不存在或鏈接至不同前驅）。若要隱藏刪除，攻擊者得重新簽署所有後續收執，須有私鑰。

5. 收執驗證通過，是否證明代理行動正確、合理且遵循政策？

答案

否。有效收執證明三件事：歸屬（此金鑰簽署此內容）、完整性（內容未更動）與排序（此收執在鏈中排後）。它不證明行動正確，名列 policy_id 的政策是否實際評估，或代理是否遵從所有規則。收執使代理行為可審核，不必然代表正確。這是本課最重要界限。

實作練習

開啟 code_samples/18-signed-receipts.ipynb 完成四個部分：

  1. 第一部分：簽署首份收執並驗證。
  2. 第二部分：竄改收執並觀察驗證失敗。
  3. 第三部分：建立三份收執鏈並驗證鏈條完整性。
  4. 第四部分：將模式應用於使用 Microsoft Agent Framework 建立的代理：將工具呼叫包裝進收執簽署，然後獨立驗證收執。 進階挑戰 1： 擴展收據結構，新增一個自選的欄位（例如，用於追蹤的請求 ID），更新標準簽名邏輯以包含該欄位，並確認收據仍能通過驗證的來回轉換。然後在簽名後修改該欄位，並確認驗證失敗。這將迫使你理解標準編碼的每一個位元組如何貢獻於簽名。

進階挑戰 2： 將你的兩張收據以 SHA-256 連結雜湊（以確定性順序串接它們的標準位元組）並將所得的摘要作為一個新欄位加到第三張收據上，再進行簽名。驗證這三張收據仍然能通過來回轉換。這即是你剛建造了一步包含證明：持有第三張收據的人可以證明前兩張存在於簽署當時，且無需揭露它們的內容。此模式即為可選披露收據在大規模中使用的模式（Merkle 承諾，RFC 6962）。

總結

加密收據為 AI 代理提供一條審計軌跡，具備：

  • 獨立可驗證性：任何持有公鑰者皆可驗證，無需依賴服務。
  • 防篡改：任何修改都會使簽名失效。
  • 可攜性：收據是一個小型 JSON 檔案，可被存檔、傳輸及於任何地方驗證。
  • 標準對齊：基於 Ed25519 (RFC 8032)、JCS (RFC 8785) 和 SHA-256，皆為廣泛部署的基本元件。

它們並非替代輸入驗證、政策強制或身份基礎設施，而是這些層的基礎。當你將代理部署於受監管的運行負載、多組織工作流，或任何未來審計者無法被假設信任你的環境中，收據即是你使審計軌跡誠實的手段。

最重要的帶走訊息：收據證明「誰在何時說了什麼」，但不證明所述內容為真實或正確。務必嚴守此區別。這是誠實來源系統和誤導性系統之間的差異。

生產檢查清單

當你準備從本課程升級到在真實環境部署簽署收據的代理時：

  • 將簽名金鑰移出開發者筆電。 使用 Azure Key Vault、AWS KMS 或硬體安全模組。簽署收據的私鑰絕不應存在版本控制或應用機器的純文字中。
  • 公開驗證公鑰。 審計者需線下驗證。標準作法是將 JWK 集合放在公開知名 URL（RFC 7517），例如 https://your-org.example.com/.well-known/agent-keys.json。
  • 外部固定鏈頭。 定期將最新鏈頭雜湊寫入透明度日誌（Sigstore Rekor、RFC 3161 時間戳機構，或第二個內部系統），讓外部方可確認「此鏈於此時存在」。
  • 不可變存儲收據。 附加式 Blob 儲存（Azure Storage 的不可變策略、AWS S3 物件鎖）可防止內部人員於儲存層重寫歷史。
  • 決定保存期限。 許多合規制度要求多年保存。規劃收據增長量（每張約 500 字節；一個每天產生 10K 呼叫的代理每年約產生 1.8 GB）。
  • 文件說明收據不涵蓋的事項。 收據證明歸屬性、完整性及排序。你的運行手冊應明確列出額外控管（輸入驗證、政策執行、速率限制、身份基礎設施）與收據一同構成治理態勢。

對保障 AI 代理安全還有更多問題？

加入 Microsoft Foundry Discord，與其他學習者會面、參加問答時段，並獲得 AI 代理相關問題解答。

課程之外

本課程涵蓋了單一收據簽署和雜湊鏈序列。相同的基元可組合為更先進的樣式，隨著治理態勢成熟你可能會遇見：

  • 選擇性揭露。 當收據欄位獨立承諾（RFC 6962 式 Merkle 樹）時，可針對特定審計者揭露特定欄位，並證明其餘未改動，且不暴露它們。當同一收據需同時滿足完整性審計（要求全面性）及像 GDPR 的資料最小化規範（審計者只看必要部分）時此非常有用。
  • 收據撤銷。 若簽署金鑰遭竄改，需要方法標示該金鑰自某時起所簽所有收據皆不信任。標準模式為短期簽署金鑰加上已公布的撤銷清單，或含撤銷條目之透明度日誌。
  • 雙方/分割簽署收據。 有些實作將簽署負載拆為執行前（authorization_*）與執行後（result_*）兩半，獨立簽名。當授權決策與觀察結果由不同角色或時間產生尤其有效。此模式可疊加本課教的收據格式。
  • 負載組合。 收據封存的是你放入 result_hash 的位元組。真實負載往往比單一工具呼叫結果豐富：預決策推理（模型預測、考慮選項、證據與完整度、風險態勢、責任鏈、守門結果）皆可置入負載，由單一收據封存。這保持收據格式簡潔，同時讓負載結構可按領域演進。
  • 跨實作相容性。 多個獨立實作（Python、TypeScript、Rust、Go）針對同格式收據使用共享測試向量相互驗證。若自行打造實作，比對已公布的測試向量可確認線路相容性。
  • 後量子遷移。 Ed25519 現今廣泛部署，但不抗量子攻擊。收據格式為演算法協調式：signature.alg 欄位可載入 ML-DSA-65（NIST 後量子簽名標準）以便遷移。規劃一段收據雙重簽名的過渡期。

相關資源

上一課

建立電腦使用代理 (CUA)

下一課

(由課程維護者決定)

免責聲明： 本文件使用 AI 翻譯服務 Co-op Translator 進行翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或曲解承擔責任。

在新工单中引用 查看 Git Blame 复制永久链接