Se lektionsvideoen: Sikring af AI-agenter med kryptografiske kvitteringer
(Lektionsvideo og miniaturebillede tilføjes af Microsoft-indholdsteamet efter sammensmeltning, der matcher mønsteret for lektion 14 / 15.)
Denne lektion vil dække:
Efter at have gennemført denne lektion vil du vide, hvordan du:
Forestil dig, at du har implementeret en AI-agent for Contoso Travel. Agenten læser kundeforespørgsler, kalder en fly-API for at se muligheder, og booker sæder på kundens vegne. I sidste kvartal behandlede agenten 50.000 bookinger.
I dag ankommer en revisor. De stiller et enkelt spørgsmål: “Vis mig, hvad din agent gjorde.”
Du overgiver dine logfiler. Revisoren kigger på dem og stiller det sværere spørgsmål: “Hvordan ved jeg, at disse logs ikke er blevet redigeret?”
Dette er audit-sprogsproblemet. De fleste agent-implementeringer i dag bygger på:
Ingen af disse kan besvare revisorens spørgsmål uden at kræve, at revisoren stoler på nogen (dig, din cloud-udbyder, din databaseleverandør). Til internt brug er den tillid ofte acceptabel. For regulerede arbejdsopgaver (finans, sundhedsvæsen, alt underlagt EU AI-loven) er det ikke.
Kryptografiske kvitteringer snævrer dette problem ind ved at gøre en underskrevet erklæring uafhængigt verificerbar. Revisoren behøver stadig en udenfor-bånd årsag til at stole på signeringsnøglen og komponenten, der producerede erklæringen. En indlejret nøgle beviser selv-konsistens, ikke udsteder-identitet eller håndhævelsesplacering.
En kvittering er et JSON-objekt, der registrerer, hvad en agent gjorde, underskrevet med en digital signatur.
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]
En minimal kvittering ser således ud:
{
"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..."
}
}
Tre egenskaber udfører arbejdet:
Signaturen. Kvitteringen underskrives af agentens gateway ved brug af en Ed25519-privatnøgle. Enhver med den tilsvarende offentlige nøgle kan verificere signaturen offline. En part, der stoler på nøglen, skal fastlåse den nøgle eller hente den fra et betroet register uden for kvitteringen. Manipulation af et hvilket som helst underskrevet felt ugyldiggør signaturen.
Kanonisk kodning. Før signering serialiseres kvitteringen ved hjælp af JSON Canonicalization Scheme (JCS, RFC 8785). Dette sikrer, at to implementeringer, der producerer samme logiske kvittering, producerer byte-identisk output. Uden kanonisk kodning ville forskellige JSON-serialisere producere forskellige signaturer for samme indhold.
Hash-dannelse. previous_receipt_hash-feltet kæder hver kvittering til den foregående. At fjerne eller omrokere en kvittering bryder den præsenterede sekvens. Opdagelse af forkortelse eller en omskrivning kontrolleret af underskriveren kræver også en fastlåst aktuel kædehoved, uafhængigt vidne bekræftet checkpoint eller autentificeret lukket population-commitment.
Sammen giver disse egenskaber tre garantier:
Du behøver ikke et specielt bibliotek til at producere en kvittering. De kryptografiske primitive er bredt tilgængelige, og logikken er et par dusin linjer Python.
De praktiske øvelser i code_samples/18-signed-receipts.ipynb gennemgår hele forløbet. Den kildekontrollerede code_samples/18-signed-receipts.execution-receipt.json registrerer den præcise notesbog-hash, Python-miljø, celleantal og tjek fra den seneste rene kørsel uden at ændre lektionens gemte output. Sammenfatningen:
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)),
},
}
Det er hele signeringspipeline. Øvelserne i notesbogen gennemgår hvert trin.
Verifikation er den inverse operation:
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
Denne funktion tager en kvittering og udstederens offentlige nøgle, og returnerer True hvis signaturen er gyldig og False ellers, inklusive når input er fejlformatet. Intet netværkskald og ingen verifikationstjeneste: når du har udstederens nøgle, er verifikationen helt lokal og offline. Det, den stadig kræver, er den nøgle, som er opnået fra et andet sted end kvitteringen selv.
For at se manipulationsdetektion i praksis gennemgår notesbogen:
tool_args_hash-feltet.Trin 4 er værd at dvæle ved. Den kvittering er internt konsistent: dens signatur er ægte for dens indhold og for den nøgle, den bærer, så den verificeres mod nøglen indeni. Den fejler kun, når den tjekkes mod udstederens rigtige nøgle. Trin 2 og 3 fanger en angriber, som ikke gendannede signaturen; trin 4 fanger den, der gjorde.
Dette er den praktiske demonstration af, at kvitteringer er manipulation-synlige: enhver ændring i et underskrevet felt bryder signaturen, forudsat at du verificerer mod en nøgle, som angriberen ikke leverede. signature-objektet selv er uden for de underskrevne bytes, og det er derfor, nøglen, du verificerer mod, skal komme et andet sted fra end kvitteringen.
En enkelt underskrevet kvittering beskytter én handling. En kæde af kvitteringer beskytter en sekvens.
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
Hver kvittering registrerer hashen af den forrige kvittering. For at fjerne kvittering 2 diskret skulle en angriber enten:
previous_receipt_hash-felt (bryder kvittering 3’s signatur), ELLERHvis den private nøgle er i et hardware key vault, og verifierende kontrollerer hver kvittering mod udstederens offentlige nøgle, opnået uafhængigt (et publiceret JWK-sæt eller en fastlåst konfigurationsværdi), er ingen af angrebene mulige uden opdagelse. At offentliggøre nøglen inde i hver kvittering er ikke nok: en angriber kan genunderskrive med deres egen nøgle og i stedet indlejre den, hvilket er fastlagt i 04_resigned_receipt.json.
Notesbogen gennemgår:
previous_receipt_hash matcher den faktiske hash af den foregående kvittering.Sådan producerer du et revisionsspor, som en ekstern revisor kan verificere under sine egne fastlåste udsteder-nøgler og kædecheckpoints uden at stole på din mutable log.
Dette er den vigtigste sektion i denne lektion. Kvitteringer er kraftfulde, men deres magt er begrænset.
Kvitteringer beviser tre ting:
Kvitteringer beviser IKKE:
policy_id, faktisk blev evalueret, eller at den ville have tilladt denne handling, hvis kontrolleret. Kvitteringen registrerer, hvad der blev påstået, ikke, hvad der blev håndhævet.Nøglen i kvitteringen er ikke den nøgle, du verificerer med. Dette følger af punkt 3, og det er det ene sted, hvor skelnen skal ændre din kode i stedet for din forståelse. public_key i eksemplet ovenfor er der, så eksemplet er selvstændigt. En verifier må aldrig stole på den. Alle kan tage en kvittering, ændre den, underskrive den med en nøgle, de har genereret, og indlejre den nøgle; resultatet verificeres perfekt mod sig selv. Det er fastlagt i 04_resigned_receipt.json i sample_receipts/, og det er derfor, verify_receipt ovenfor tager nøglen som argument i stedet for at læse den ud af kvitteringen. Opnå udstederens nøgle uafhængigt, fra JWK-sættet i Produktionschecklisten nedenfor eller en anden anker, som du fastlagde på forhånd, og verificer mod den. En signatur tjekket med en nøgle, der ankom i samme konvolut, beviser kun, at konvolutten er selvkonsistent.
Denne grænse har betydning af to grunde:
En almindelig fejl er at antage, at “vi har kvitteringer” betyder “vi er styret.” Det er det ikke. Kvitteringer er en grundsten. Styring er systemet, du bygger ovenpå.
Punkt 3 ovenfor er værd sin egen sektion: en handlingskvittering siger “denne nøgle underskrev dette indhold,” aldrig “et menneske godkendte dette.” For højrisikohandlinger (refusioner, sletninger, pengetransfer) kan en separat godkender underskrift binde den nøjagtige handling. At forbinde den nøgle til et menneske og tjekke menneskelig tilstedeværelse forbliver separate ansvar.
Den efterfølgende notesbog code_samples/human-authorization-receipts.ipynb tilføjer en anden kvitteringstype, human.approval.v1, i samme konvolutform som lektionens kvitteringer (en typed payload underskrevet med Ed25519 over dens kanoniske JCS-bytes, med signature-objektet uden for de underskrevne bytes). En godkendernøgle underskriver hel kanonisk handling og dens digest; en agentnøgle underskriver en erklæring med samme handlingsdigest og en parent_approval_ref, receipt_hash for godkendelsen, samme konvention som previous_receipt_hash i kæden, du byggede ovenfor. Et verify_chain går igennem begge artefakter under separate fastlåste nøgleregistre (godkender nøgler mod agent nøgler), så kodevejen deles, men myndighederne aldrig gør.
Egenskaben dette køber, nøje formuleret: den fastlåste godkendernøgle underskrev denne eksakte handling, og agentnøglen underskrev senere en erklæring, der bar samme handlingsdigest. Det er brugbart bevis, men det er ikke alene bevis for, at handlingen blev udført. For at styre udførelse skal den eksakte godkendelse også reserveres og forbruges én gang ved den faktiske udførergrænse; ukendte udbyderresultater må forblive ukendte frem for blindt at blive gentaget. Notesbokens afvisningsfaciliteter tester kvitteringskædelaget:
Hver fejl nægtes med en distinkt grund, så en revisor, der læser en afvisning, kan se, om myndighed blev forældet, eller den påståede handling ændrede sig. Verifikation er skrivebeskyttet og gentagelig: den forbruger ikke godkendelsen eller påkalder en udbyder. En separat udfører har brug for holdbar, atomar genafspilningsbeskyttelse og eksplicit succes, fiasko og ubestemte resultater. Menneskelig godkendelseskvittering er en uddannelsesmæssig sammensætning defineret af denne lektion, ikke en kvitteringstype defineret af draft-farley-acta-signed-receipts.
Python-koden i denne lektion er bevidst minimal, så du kan læse hver linje og forstå præcis, hvad der sker. I produktion har du to muligheder:
Byg direkte på de kryptografiske primitivere. De 50 linjer, du så ovenfor, er tilstrækkelige til mange brugstilfælde. PyNaCl (Ed25519) og jcs-pakken (kanonisk JSON) er velholdte og reviderede biblioteker.
Brug et produktionsmodent kvitteringsbibliotek. Flere open source-projekter implementerer det samme mønster med yderligere funktioner (nøglerotation, batchverifikation, JWK Set-distribution, integration med policy-motorer):
draft-farley-acta-signed-receipts, revision 02). Denne lektions flade pædagogiske kvittering adskiller sig fra draftets {payload, signature}-konvolut og præsenteres ikke som en konform implementering. Draftet offentliggør en fælles konformitetssuite (agent-governance-testvectors) til implementeringer, der retter sig mod dets wire-format.protect-mcp (npm) og @veritasacta/verify (npm) pakkerne tilbyder en Node-baseret implementering af kvitteringssignering og offline verifikation, designet til at omslutte enhver MCP-server med et manipulationssikkert revisionsspor, inklusive et holdt-til-sambrug flow, hvor en pauset handling udsender en godkendelseskvittering bundet til handlingsdigesten (WebAuthn-understøttet i desktop-flowet), samme godkendelseskvitteringsmønster som det menneskelige autorisationsnotebook ovenfor.pip install nobulex) leverer samme Ed25519 + JCS signeringsmønster i Python med LangChain- og CrewAI-integrationer, inklusive offentliggjorte krydsvalideringstestvektorer og et compliance-mapping bidraget via OWASP PR #2210.Beslutningen mellem at rulle sin egen løsning og bruge et bibliotek svarer til valget mellem at skrive sit eget JWT-bibliotek og bruge et testet et: Begge er rimelige; biblioteket sparer tid og reducerer revisionsfladen; fra-skratch-tilgangen tvinger dig til at forstå hver primitive. Denne lektion underviser i fra-skratch-vejen, så du har fundamentet til begge valg.
Test din forståelse inden du går videre til praksisøvelsen.
1. En kvittering signeres med agentens private Ed25519-nøgle. Revisor har kun den offentlige nøgle. Kan revisor verificere kvitteringen offline?
2. En angriber ændrer policy_id-feltet i en kvittering for at påstå, at det var styret af en mere lempelig politik. Signaturen var over den oprindelige nyttelast. Hvad sker der under verifikationen?
3. Hvorfor inkluderer kvitteringen en tool_args_hash og result_hash i stedet for rå argumenter og resultat?
4. previous_receipt_hash-feltet linker hver kvittering til dens forgænger. Hvis en angriber stille sletter en kvittering fra midten af en kæde, hvad bliver ugyldigt?
5. En kvittering verificeres rent. Beviser det, at agentens handling var korrekt, velment eller overholdende politik?
Åbn code_samples/18-signed-receipts.ipynb og gennemfør alle fire sektioner:
Strækudfordring 1: udvid kvitteringsskemaet med et ekstra felt efter eget valg (fx et anmodnings-ID til sporing), opdater den kanoniske signeringslogik til at inkludere det, og bekræft, at kvitteringen stadig kan gennemløbe verifikation. Modifier derefter feltet efter signering og bekræft, at verifikationen fejler. Det tvinger dig til at forstå, hvordan hver byte i den kanoniske kodning bidrager til signaturen.
Strækudfordring 2: SHA-256-hash to af dine kvitteringer sammen (kæd deres kanoniske bytes i en deterministisk rækkefølge) og indlejre den resulterende digest som et nyt felt på en tredje kvittering før signering. Verificer at alle tre kvitteringer stadig kan gennemløbe. Du har netop bygget et énstegs inklusionsbevis: enhver med den tredje kvittering kan bevise, at de første to eksisterede på tidspunktet for signeringen, uden at afsløre deres indhold. Dette er mønsteret, som kvitteringer med selektiv afsløring anvender i stor skala (Merkle-forpligtelser, RFC 6962).
Kryptografiske kvitteringer giver AI-agenter et revisionsspor, som er:
De er ikke en erstatning for input validering, politikhåndhævelse, executor tilladelse, resultatbevis, komplethedskontroller eller identitetsinfrastruktur. De udgør fundamentet for disse lag. I regulerede eller multi-organisatoriske workflows gør kvitteringer specifikke udstederaftaler uafhængigt kontrollerbare under revisorens egen tillidskonfiguration.
Det vigtigste hovedbudskab: kvitteringer beviser, at en bestemt nøgle signerede bestemt indhold. Et medbragt tidsstempel er en underskrivers påstand, medmindre det særskilt tidsattesteres. En kvittering beviser ikke, at dens indhold var sandt, at en handling blev udført, eller at optagelses-sættet er komplet. Hold disse skel skarpt.
Når du er klar til at avancere fra denne lektion til at deployere kvitteringssignerede agenter i et rigtigt miljø:
Deltag i Microsoft Foundry Discord for at møde andre elever, deltage i åbne kontortimer og få besvaret dine spørgsmål om AI-agenter.
Denne lektion dækker enkeltkvitteringssignering og hash-kædede sekvenser. De samme primitivere sammensættes i flere mere avancerede mønstre, som du kan støde på efterhånden som din governance-opsætning udvikler sig:
authorization_*) og efter-eksekverings (result_*) halvdele med uafhængige signaturer, brugbart når autorisationsbeslutningen og det observerede resultat produceres af forskellige aktører eller på forskellige tidspunkter. Det bygger ovenpå kvitteringsformatet undervist i denne lektion.result_hash. Reelle nyttelaster er ofte rigere end et enkelt værktøjskalds resultat: for-beslutningsbegrundelse (modelprediktion, overvejede muligheder, evidens og dens komplethed, risikostilling, ansvarskæde, portudfald) kan alle ligge internt i nyttelasten, forseglet af en enkelt kvittering. Det holder kvitteringsformatet minimalt, mens nyttelastskemaer kan udvikle sig domæne-for-domæne.alg-label alene er ikke migration: en profil skal definere ML-DSA nøglekodning, kanoniske signerede bytes, verifikation, relying-party-politik, downgrade-resistens og overgangssemantik. Planlæg og test en dual-signatur overgang mod delte vektorer før kompatibilitetskrav stilles.Oprettelse af lokale AI-agenter
Ansvarsfraskrivelse: Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten Co-op Translator. Selvom vi bestræber os på nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det originale dokument på dets oprindelige sprog bør betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse.