Panoorin ang video ng aralin: Pag-secure ng AI Agents gamit ang Cryptographic Receipts
(Idadagdag ng Microsoft content team ang video ng aralin at thumbnail pagkatapos ng pagsasama, na tumutugma sa pattern ng aralin 14 / 15.)
Saklawin ng araling ito ang:
Pagkatapos makumpleto ang araling ito, malalaman mo kung paano:
Isipin na nag-deploy ka ng AI agent para sa Contoso Travel. Binabasa ng agent ang mga kahilingan ng customer, tumatawag sa flights API upang maghanap ng mga opsyon, at nagbubook ng mga upuan para sa customer. Noong nakaraang quarter, naproseso ng agent ang 50,000 bookings.
Ngayon ay dumating ang isang auditor. Nagtanong siya ng simpleng tanong: “Ipakita mo sa akin ang ginawa ng iyong agent.”
Ibinigay mo ang iyong mga log file. Tiningnan ito ng auditor at nagtanong ng mas mahirap na tanong: “Paano ko malalaman na hindi na-edit ang mga log na ito?”
Ito ang problema sa audit trail. Karamihan sa mga deployment ng agent ngayon ay umaasa sa:
Wala sa mga ito ang makakasagot sa tanong ng auditor nang hindi kinakailangang magtiwala ang auditor sa isang tao (ikaw, ang iyong cloud provider, ang vendor ng iyong database). Para sa panloob na gamit, madalas tanggap ang pagtitiwala na iyon. Para sa mga regulated workload (pananalapi, pangangalagang pangkalusugan, anumang sakop ng EU AI Act), hindi ito tinatanggap.
Nililimitahan ng cryptographic receipts ang problemang ito sa pamamagitan ng paggawa ng isang signed na pahayag na maaaring i-verify nang independiyente. Kailangan pa rin ng auditor ng ibang paraan upang magtiwala sa signing key at sa component na gumawa ng pahayag. Ang nakalakip na key ay nagpapatunay ng sariling pagkakapare-pareho, hindi ng pagkakakilanlan ng issuer o ng lugar ng pagpapatupad.
Ang receipt ay isang JSON object na nagrerekord ng ginawa ng isang agent, na may digital signature.
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]
Ang isang minimal na receipt ay ganito:
{
"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..."
}
}
Tatlong katangian ang gumagana dito:
Ang signature. Nilagdaan ang receipt ng gateway ng agent gamit ang isang Ed25519 private key. Sinuman na may kaukulang public key ay maaaring i-verify ang signature offline. Kailangang i-pin ng isang party ang key na iyon o i-resolve ito mula sa isang trusted registry sa labas ng receipt. Ang pagmanipula sa anumang nilagdaang field ay nagpapawalang-bisa sa signature.
Canonical encoding. Bago pamagitan, ang receipt ay sine-serialize gamit ang JSON Canonicalization Scheme (JCS, RFC 8785). Tinitiyak nito na dalawang implementasyon na gumagawa ng parehong lohikal na receipt ay makakagawa ng byte-identical na output. Kung walang canonicalization, magkakaiba ang mga serializer ng JSON sa paglikha ng mga signature para sa parehong nilalaman.
Hash chaining. Ang previous_receipt_hash field ay nag-uugnay ng bawat receipt sa nauna nito. Ang pagtanggal o pagbabago ng isang receipt ay nagpapabasag sa ipinakitang sekwensya. Ang pagtuklas ng pag-truncate o pag-rewrite na kontrolado ng signer ay nangangailangan din ng naka-pin na current chain head, independiyenteng nasaksihang checkpoint, o authenticated closed-population commitment.
Sama-sama, ang mga katangiang ito ay nagbibigay ng tatlong garantiya:
Hindi mo kailangan ng espesyal na library para gumawa ng receipt. Malawak ang pagkakaroon ng cryptographic primitives at ilang dosenang linya lang ng Python ang kinakailangan sa lohika.
Inilalahad ng mga hands-on na pagsasanay sa code_samples/18-signed-receipts.ipynb ang buong daloy. Itinatala ng source-controlled na code_samples/18-signed-receipts.execution-receipt.json ang eksaktong notebook hash, Python environment, bilang ng cell, at mga tseke mula sa pinakabagong malinis na pagtakbo nang hindi binabago ang mga na-save na output ng aralin. Ang buod:
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)),
},
}
Iyan ang buong pipeline ng pag-sign. Ang mga pagsasanay sa notebook ay naglalakad sa bawat hakbang.
Ang verification ay ang kabaligtaran na operasyon:
import base64
import hashlib
from nacl import signing
from nacl.exceptions import CryptoError
from jcs import canonicalize
def b64url_decode(s: str) -> bytes:
# Strict: Python's decoder skips characters outside the alphabet and also
# accepts padding, the standard +/ alphabet and non-zero spare bits.
# Re-encoding and comparing accepts only the one unpadded base64url form.
padding = "=" * ((4 - len(s) % 4) % 4)
data = base64.urlsafe_b64decode(s + padding)
if base64.urlsafe_b64encode(data).decode("ascii").rstrip("=") != s:
raise ValueError("not canonical unpadded base64url")
return data
def verify_receipt(receipt: dict, trusted_public_key: str) -> bool:
# trusted_public_key is the issuer's key, obtained from somewhere other
# than this receipt. Never use receipt["signature"]["public_key"] here:
# see "What Receipts Prove (and What They Do Not)" below.
# Fails closed: anything malformed returns False instead of raising.
if not isinstance(receipt, dict) or not isinstance(trusted_public_key, str):
return False
sig_obj = receipt.get("signature")
if not isinstance(sig_obj, dict) or sig_obj.get("alg") != "EdDSA":
return False
sig_b64 = sig_obj.get("sig")
if not isinstance(sig_b64, str):
return False
try:
# Reconstruct the payload that was actually signed (everything except signature).
payload = {k: v for k, v in receipt.items() if k != "signature"}
canonical_bytes = canonicalize(payload)
verify_key = signing.VerifyKey(b64url_decode(trusted_public_key))
verify_key.verify(canonical_bytes, b64url_decode(sig_b64))
return True
except (CryptoError, TypeError, ValueError, KeyError, OverflowError):
return False
except Exception:
# An undecodable key or signature, or a payload that cannot be
# canonicalized: fail closed rather than raise.
return False
Tinanggap ng function na ito ang isang receipt at ang public key ng issuer, at nagbabalik ng True kung ang signature ay wasto at False kung hindi, kabilang na kapag mali ang input. Walang network call at walang verification service: kapag hawak mo na ang key ng issuer, ang verification ay lubos na lokal at offline. Ang kailangan pa rin nito ay ang key na iyon, na nakuha mula sa ibang pinanggalingan maliban sa receipt mismo.
Para makita ang pagtuklas ng pagmanipula sa aksyon, ang notebook ay naglalakad sa:
tool_args_hash na field.Ang Hakbang 4 ang dapat talagang pag-ukulan ng pansin. Ang receipt na iyon ay internally consistent: ang signature nito ay tunay para sa mga nilalaman at para sa key na dala nito, kaya ito ay na-verify laban sa key sa loob nito. Nabibigo lamang ito kapag tiningnan laban sa totoong key ng issuer. Nahuhuli ng mga Hakbang 2 at 3 ang attacker na hindi nagkaroon ng sapat na sipag na muling pumirma; nahuhuli ang Hakbang 4 ang attacker na muling pumirma.
Ito ang praktikal na demonstrasyon na ang mga receipt ay tamper-evident: anumang pagbabago sa nilagdaang field ay nagpapabasag sa signature, basta i-verify mo laban sa key na hindi ibinigay ng attacker. Ang signature na object mismo ay nasa labas ng nilagdaang bytes, kaya’t ang key na ginagamit mo sa verification ay kailangang manggaling sa ibang lugar maliban sa receipt.
Ang isang solong signed receipt ay nagpoprotekta sa isang aksyon. Ang isang chain ng mga receipt ay nagpoprotekta sa isang sunud-sunod.
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
Ina-itala ng bawat receipt ang hash ng naunang receipt. Para tahimik na tanggalin ang receipt 2, kailangang gawin ng attacker ang alinman sa mga sumusunod:
previous_receipt_hash na field ng receipt 3 (binabasag ang signature ng receipt 3), OKung ang private key ay naka-imbak sa hardware key vault at ang mga verifier ay sinusuri ang bawat receipt laban sa public key ng issuer na nakuha nang independyente (isang inilathalang JWK Set o pinned config value), wala sa mga atakeng ito ang maaaring mangyari nang hindi natutuklasan. Hindi sapat ang paglalathala ng key sa loob ng bawat receipt: maaaring mag-resign ang attacker gamit ang sarili nilang key at ilagay iyon, na isang pamilyar na fixture 04_resigned_receipt.json.
Ang notebook ay naglalakad sa:
previous_receipt_hash ng bawat receipt ay tumutugma sa aktwal na hash ng naunang receipt.Ganito ka gumagawa ng audit trail na kayang i-verify ng external na auditor sa ilalim ng sariling pinned issuer keys at chain checkpoints, nang hindi kailangan umasa sa iyong pabago-bagong log store.
Ito ang pinakamahalagang bahagi ng araling ito. Malakas ang mga receipt ngunit may hangganan ang kanilang kapangyarihan.
Tatlong bagay ang pinapatunayan ng mga receipt:
Hindi pinapatunayan ng mga receipt:
policy_id ay talagang na-evaluate, o na pahihintulutan nito ang aksyon kung ito ay tinsek. Ini-record ng receipt kung ano ang inangkin, hindi kung ano ang ipinatupad.Ang key sa receipt ay hindi ang key na ginagamit mo sa pag-verify. Ito ay sumusunod sa punto 3, at ito ang nag-iisang lugar kung saan kailangang baguhin ang iyong code sa halip na ang iyong pag-unawa. Ang public_key sa halimbawa sa itaas ay naroon upang gawing self-contained ang halimbawa. Hindi dapat magtiwala ang verifier dito. Maaaring kunin ng sinuman ang isang receipt, baguhin ito, pirmahan ito gamit ang key na kanilang ginawa, at isingit ang key na iyon; ang resulta ay perpektong naverify laban sa sarili nito. Iyan ay fixture 04_resigned_receipt.json sa sample_receipts/, at kaya nagpapatanggap ang verify_receipt sa itaas ng key bilang argumento sa halip na basahin mula sa receipt. Kumuha ng key ng issuer nang independiyente, mula sa JWK Set sa Production Checklist sa ibaba o mula sa ibang naunang na-pin na anchor, at i-verify laban doon. Ang signature na na-verify gamit ang key na dumating sa parehong sobre ay nagpapatunay lamang na ang sobre ay self-consistent.
Mahalaga ang hangganang ito sa dalawang dahilan:
Isang pangkaraniwang pagkakamali ang mag-assume na “mayroon tayong receipt” ay katumbas ng “tayo ay pinamamahalaan.” Hindi ganoon. Ang mga receipt ay pundasyon. Ang pamamahala ay ang sistema na itinatayo mo sa ibabaw.
Karapat-dapat ang item 3 sa sarili nitong seksyon: sinasabi ng action receipt na “nilagdaan ng key na ito ang nilalamang ito,” hindi kailanman “ang tao ay nag-authorize nito.” Para sa mga aksyon na mataas ang panganib (refunds, pagtanggal, wire transfers), maaaring mag-bind ang hiwalay na lagda ng approver sa eksaktong aksyon. Ang pagkonekta ng key na iyon sa tao at pagtsek ng presensya ng tao ay nananatiling hiwalay na responsibilidad.
Idinagdag ng follow-on notebook na code_samples/human-authorization-receipts.ipynb ang pangalawang uri ng receipt, human.approval.v1, sa parehong hugis ng sobre tulad ng mga receipt ng aralin (isang typed payload na nilagdaan ng Ed25519 sa canonical JCS bytes nito, na may signature na object sa labas ng nilagdaang bytes). Nilagdaan ng approver key ang buong canonical na aksyon at ang digest nito; nilagdaan ng agent key ang isang pahayag na naglalaman ng kaparehong action digest at isang parent_approval_ref, ang receipt_hash ng approval, parehong convention tulad ng previous_receipt_hash sa chain na binuo mo sa itaas. Isang verify_chain ang naglalakad sa parehong artifact sa ilalim ng hiwalay na pinned key registry (approver keys laban sa agent keys), kaya shared ang code path ngunit hindi magkakapareho ang mga awtoridad.
Ang katangiang binibili nito, na maingat na ipinahayag: nilagdaan ng pinned approver key ang eksaktong aksyon na ito, at nilagdaan ng agent key kalaunan ang pahayag na nagdala ng parehong action digest. Kapaki-pakinabang iyon bilang ebidensiya, ngunit hindi ito katibayan na naipatupad ang aksyon. Upang makontrol ang pagpapatupad, ang eksaktong pag-apruba ay kailangang nakareserba rin at nagamit nang isang beses sa aktwal na executor boundary; ang hindi kilalang mga resulta ng provider ay kailangang manatiling hindi alam sa halip na ipilitang ulitin nang walang uliran. Sinusubukan ng refusal fixtures ng notebook ang layer ng receipt-chain:
Bawat kabiguan ay tumatanggi na may kakaibang dahilan, kaya ang isang tagasuri na nagbabasa ng pagtanggi ay maaaring malaman kung ang awtoridad ay lipas na o nagbago ang inaangking aksyon. Ang beripikasyon ay pang-basang lamang at paulit-ulit: hindi nito kinokonsumo ang pag-apruba o tinatawag ang isang provider. Isang hiwalay na tagapagpatupad ang nangangailangan ng matibay, atomic na proteksyon laban sa replay at hayagang tagumpay, kabiguan, at hindi tiyak na resulta. Ang resibo ng pag-apruba ng tao ay isang pang-edukasyong komposisyon na tinukoy ng araling ito, hindi isang uri ng resibo na tinukoy ng draft-farley-acta-signed-receipts.
Ang Python code sa araling ito ay sadyang minimal upang mabasa mo ang bawat linya at maintindihan kung ano mismo ang nangyayari. Sa produksyon, may dalawang opsyon ka:
Magbuild nang diretso gamit ang cryptographic primitives. Ang 50 linya na nakita mo sa itaas ay sapat para sa maraming use case. Ang PyNaCl (Ed25519) at ang jcs package (canonical JSON) ay mga maayos na maintained at na-audit na mga library.
Gumamit ng production receipt library. Ilang open-source na proyekto ang nagpapatupad ng parehong pattern na may dagdag na features (key rotation, batch verification, JWK Set distribution, integration with policy engines):
draft-farley-acta-signed-receipts, rebisyon 02). Ang flat educational receipt ng araling ito ay nagkakaiba sa draft na {payload, signature} envelope at hindi inilahad bilang isang conformant na implementasyon. Naglalathala ang draft ng isang shared conformance suite (agent-governance-testvectors) para sa mga implementasyong tumutugon sa wire format nito.protect-mcp (npm) at @veritasacta/verify (npm) packages ay nagbibigay ng Node-based na implementasyon ng receipt signing at offline verification, na inilaan para balutin ang anumang MCP server ng isang tamper-evident audit trail, kabilang ang held-for-co-sign na daloy kung saan ang nahintuang aksyon ay naglalabas ng approval receipt na nakatali sa action digest (WebAuthn-backed sa desktop flow), ang parehong approval-receipt pattern gaya ng human-authorization notebook sa itaas.pip install nobulex) ay nagbibigay ng parehong Ed25519 + JCS signing na pattern sa Python na may LangChain at CrewAI integrasyon, kabilang ang na-publish na cross-validation test vectors at isang compliance mapping na naiambag sa pamamagitan ng OWASP PR #2210.Ang desisyon sa pagitan ng paggawa ng sarili mong sistema at paggamit ng library ay parang desisyon sa pagitan ng pagsusulat ng sariling JWT library at paggamit ng nasubok na isa: parehong makatwiran; ang library ay nakakatipid ng oras at nagpapaliit ng audit surface; ang from-scratch na paraan ay pilitin kang maintindihan ang bawat primitive. Itinuturo ng araling ito ang from-scratch path upang magkaroon ka ng pundasyon para sa alinmang pagpipilian.
Subukan ang iyong pagkaintindi bago lumipat sa practice exercise.
1. Ang isang receipt ay nilagdaan gamit ang pribadong Ed25519 key ng agent. Ang auditor ay may hawak lamang ng public key. Maaari bang i-verify ng auditor ang receipt nang offline?
2. Isang attacker ang nag-modify ng policy_id field ng isang receipt upang ipahayag na ito ay pinamamahalaan ng mas maluwag na patakaran. Ang lagda ay ginawa sa orihinal na payload. Ano ang mangyayari sa pag-verify?
3. Bakit naglalaman ang receipt ng tool_args_hash at result_hash imbes na ang raw na mga argumento at resulta?
4. Ang previous_receipt_hash field ay nag-uugnay ng bawat receipt sa nauna nito. Kung tahimik na burahin ng attacker ang isang receipt mula sa gitna ng chain, ano ang magiging invalid?
5. Malinis ang verification ng isang receipt. Ipinapatunay ba nito na ang aksyon ng agent ay tama, wasto, o sumusunod sa patakaran?
Buksan ang code_samples/18-signed-receipts.ipynb at kumpletuhin ang apat na seksyon:
Stretch challenge 1: palawakin ang schema ng receipt gamit ang isa pang field na pinili mo (halimbawa, request ID para sa tracing), i-update ang canonical signing logic para isama ito, at tiyaking ang receipt ay nagro-round-trip pa rin sa verification. Pagkatapos ay baguhin ang field pagkatapos ng paglagda at tiyaking mabibigo ang verification. Pinipilitan kang maintindihan kung paano nakakatulong ang bawat byte ng canonical encoding sa lagda.
Stretch challenge 2: I-SHA-256 hash ang dalawang receipt mo nang magkasama (i-concatenate ang canonical bytes nila sa deterministic na order) at i-embed ang resulting digest bilang bagong field sa ikatlong receipt bago ito lagdaan. I-verify na ang tatlong receipt ay nagro-round-trip pa rin. Kakatayo mo lang ng isang one-step inclusion proof: sinuman na may hawak ng ikatlong receipt ay maipapakita na umiiral ang unang dalawang receipt noong panahon ng paglagda, nang hindi kailangang ilantad ang nilalaman nila. Ito ang pattern na ginagamit ng selective-disclosure receipts sa malakihang operasyon (Merkle commitments, RFC 6962).
Ang cryptographic receipts ay nagbibigay sa mga AI agent ng audit trail na:
Hindi ito kapalit ng input validation, pagpapatupad ng patakaran, executor admission, ebidensiya ng kinalabasan, completeness controls, o identity infrastructure. Ito ay pundasyon para sa mga layer na iyon. Sa mga regulated o multi-organisasyong workflows, ang mga receipt ay nagiging specific na pahayag ng issuer na maaaring suriin nang independyente sa ilalim ng trust configuration ng auditor.
Ang pinakamahalagang takeaway: ang mga receipt ay nagpapatunay na ang partikular na susi ang lumagda sa partikular na nilalaman. Ang dala na timestamp ay isang signer assertion maliban kung ito ay hiwalay na na-time-attest. Ang receipt ay hindi nagpapatunay na ang nilalaman ay totoo, na naisakatuparan ang isang aksyon, o na ang rekord na set ay kumpleto. Mahigpit na panatilihin ang mga pagkakaibang ito.
Kapag handa ka nang magtapos sa araling ito patungo sa pag-deploy ng mga receipt-signed agents sa totoong kapaligiran:
Sumali sa Microsoft Foundry Discord upang makipagkita sa ibang mga nag-aaral, dumalo sa office hours, at makakuha ng sagot sa iyong mga tanong tungkol sa AI Agents.
Saklaw ng araling ito ang single-receipt signing at hash-chained sequences. Ang parehong mga primitives ay bumubuo ng ilang mas advanced na mga pattern na maaari mong matugunan habang umuunlad ang iyong governance posture:
authorization_*) at post-execution (result_*) na kalahati na may independyenteng mga lagda, kapaki-pakinabang kapag ang desisyon ng awtorisasyon at ang naobserbahang resulta ay ginawa ng magkaibang mga aktor o sa ibang mga oras. Ito ay nagbubuo nang additive sa format ng receipt na itinuturo sa araling ito.result_hash. Ang mga totoong mundo na payload ay madalas na mas masagana kaysa sa isang solong resulta ng tool call: ang pre-decision reasoning (model prediction, mga opsyon na isinasaalang-alang, ebidensiya at ang completeness nito, risk posture, accountability chain, gate outcome) ay lahat maaaring manirahan sa loob ng payload, na sinelyuhan ng isang solong receipt. Pinananatiling minimal ang format ng receipt habang pinapayagan ang mga payload schema na umunlad ayon sa domain.alg label lamang ay hindi migration: kailangang tukuyin ng profile ang ML-DSA key encoding, canonical signed bytes, verification, relying-party policy, downgrade resistance, at transition semantics. Magplano at subukan ang dual-signature transition laban sa mga shared vector bago gumawa ng mga pahayag tungkol sa compatibility.Paglikha ng mga Lokal na AI na Ahente
Pagtatanggi: Ang dokumentong ito ay isinalin gamit ang serbisyo ng AI translation na Co-op Translator. Bagama’t nagsusumikap kami para sa katumpakan, pakatandaan na ang awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang maling pagkakaintindi o maling interpretasyon na nagmula sa paggamit ng pagsasaling ito.