Ders videosunu izleyin: Kriptografik Makbuzlarla AI Ajanlarını Güvence Altına Alma
(Ders videosu ve küçük resim, birleştirme sonrası Microsoft içerik ekibi tarafından, ders 14 / 15 kalıbına uygun şekilde eklenecektir.)
Bu ders şunları kapsayacak:
Bu dersi tamamladıktan sonra şunları bileceksiniz:
Contoso Travel için bir AI ajanı oluşturduğunuzu hayal edin. Ajan müşteri isteklerini okur, uçuşlar API’sini çağırır, seçenekleri araştırır ve müşterinin adına koltuk rezervasyonu yapar. Geçen çeyrekte, ajan 50.000 rezervasyon işledi.
Bugün bir denetçi gelir. Basit bir soru sorar: “Ajanınız ne yaptı, gösteriniz.”
Günlük dosyalarınızı teslim edersiniz. Denetçi onları inceler ve daha zor bir soru sorar: “Bu günlüklerin düzenlenmediğini nasıl bilebilirim?”
Bu denetim izi sorunudur. Bugün çoğu ajan dağıtımı şunlara dayanır:
Bunların hiçbiri denetçinin sorusuna yanıt veremez, denetçinin birine (size, bulut sağlayıcınıza, veritabanı satıcınıza) güvenmesini gerektirir. Dahili kullanım için bu güven çoğunlukla kabul edilebilir. Düzenlemeye tabi iş yükleri için (finans, sağlık, AB AI Yasası kapsamındaki herhangi bir şey) bu geçerli değildir.
Kriptografik makbuzlar her ajan eyleminin bağımsız olarak doğrulanabilir olmasını sağlar. Denetçinin size güvenmesine gerek yoktur. Sadece genel anahtarınız ve makbuzun kendisi gerekir.
Bir makbuz, bir ajanın ne yaptığını kaydeden, dijital imza ile imzalanmış bir JSON nesnesidir.
flowchart LR
A[Temsilci bir aracı çağırır] --> B[Makbuz yükünü oluştur]
B --> C[JSON RFC 8785'i kanonikleştir]
C --> E[Kanonik baytları Ed25519 ile imzala]
E --> F[İmzalı makbuz]
F --> G[Denetçi çevrimdışı doğrular]
G --> H{İmza geçerli mi?}
H -- yes --> I[Müdahale kanıtı]
H -- no --> J[Makbuz reddedildi]
Minimal bir makbuz şu şekildedir:
{
"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..."
}
}
Üç özellik çalışmayı yapıyor:
İmza. Makbuz, ajanın ağ geçidi tarafından Ed25519 özel anahtarı kullanılarak imzalanır. Karşılık gelen genel anahtara sahip herkes imzayı çevrimdışı doğrulayabilir. Herhangi bir alanın tahrif edilmesi imzayı geçersiz kılar.
Kanonik kodlama. İmzalamadan önce, makbuz JSON Kanonizasyon Şeması (JCS, RFC 8785) kullanılarak serileştirilir. Bu, aynı mantıksal makbuzu üreten iki uygulamanın bayt olarak tamamen aynı çıktıyı üretmesini sağlar. Kanonizasyon olmasaydı, farklı JSON serileştiricileri aynı içerik için farklı imzalar üretirdi.
Hash zincirleme. previous_receipt_hash alanı her makbuzu öncekine bağlar. Bir makbuzu kaldırmak veya sırasını değiştirmek, ondan sonraki tüm makbuzları bozar. Tahrif, bireysel imzalar atlatılsa bile zincir seviyesinde görünür hale gelir.
Bu özellikler birlikte üç garantiyi sağlar:
Makbuz üretmek için özel bir kitaplığa ihtiyacınız yok. Kriptografik ilkel fonksiyonlar yaygın olarak mevcuttur ve mantık birkaç düzine Python satırıdır.
code_samples/18-signed-receipts.ipynb içindeki uygulamalı egzersizler tam akışı gösterir. Özet versiyon:
import json
import hashlib
import base64
from nacl import signing
from jcs import canonicalize # RFC 8785 kanonik 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()}"
# İmzalama anahtarı oluşturun veya yükleyin (üretimde, anahtar kasasında saklayın)
signing_key = signing.SigningKey.generate()
verify_key = signing_key.verify_key
# Makbuz yükünü oluşturun (henüz imza yok)
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,
}
# JCS baytlarını doğrudan kanonikleştirip imzalayın. PureEdDSA dahili olarak karmalar.
canonical_bytes = canonicalize(payload)
signature_bytes = signing_key.sign(canonical_bytes).signature
# Yapılandırılmış bir imza nesnesi ekleyin.
receipt = {
**payload,
"signature": {
"alg": "EdDSA",
"sig": b64url_nopad(signature_bytes),
"public_key": b64url_nopad(bytes(verify_key)),
},
}
Bu, tüm imzalama hattıdır. Defterdeki egzersizlerde her adım adım gösterilir.
Doğrulama ters işlemdir:
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:
# İmza yapılandırılmış bir nesnedir: {"alg", "sig", "public_key"}.
sig_obj = receipt.get("signature")
if not sig_obj or sig_obj.get("alg") != "EdDSA":
return False
# Aslında imzalanan yükü yeniden oluşturun (imza hariç her şey).
payload = {k: v for k, v in receipt.items() if k != "signature"}
canonical_bytes = canonicalize(payload)
try:
verify_key = signing.VerifyKey(b64url_decode(sig_obj["public_key"]))
verify_key.verify(canonical_bytes, b64url_decode(sig_obj["sig"]))
return True
except BadSignatureError:
return False
Bu fonksiyon bir makbuz alır ve imza geçerliyse True, değilse False döner. Ağ çağrısı yok, servis bağımlılığı yok, üçüncü tarafa güvenme gereği yoktur.
Tahrif tespitini göstermek için defter şunları yapar:
tool_args_hash alanının bir baytını değiştirmek.Bu, makbuzların tahrif fark edilir olduğunu pratik olarak gösterir: her türlü değişiklik, ne kadar küçük olursa olsun imzayı bozar.
Tek bir imzalı makbuz bir eylemi korur. Makbuz zinciri ise bir diziyi korur.
flowchart LR
R0[Makbuz 0<br/>başlangıç] --> R1[Makbuz 1]
R1 --> R2[Makbuz 2]
R2 --> R3[Makbuz 3]
R1 -. previous_receipt_hash .-> R0
R2 -. previous_receipt_hash .-> R1
R3 -. previous_receipt_hash .-> R2
Her makbuz öncekine ait makbuzun hash’ini kaydeder. Makbuz 2’yi sessizce kaldırmak için bir saldırgan şunu yapmalıdır:
previous_receipt_hash alanını değiştirmek (makbuz 3’ün imzasını bozar), YA DAÖzel anahtar bir donanım anahtar kasasında ise ve her makbuzla genel anahtarı yayınlıyorsanız, bu saldırıların hiçbiri tespit edilmeden mümkün değildir.
Defterde şunlar gösterilir:
previous_receipt_hash alanının önceki makbuzun gerçek hash’iyle eşleştiğini doğrulamak.Bu şekilde, dış denetçinin size güvenmeden doğrulayabileceği bir denetim izi oluşturmuş olursunuz.
Bu dersin en önemli bölümüdür. Makbuzlar güçlüdür ama gücü sınırlıdır.
Makbuzlar üç şeyi kanıtlar:
Makbuzlar kanıtlamaz:
policy_id içinde belirtilen politikanın gerçekten değerlendirilip değerlendirilmediği ya da kontrol edilse bu eyleme izin verilip verilmeyeceği. Makbuz, iddia edilenleri değil, uygulananı kaydeder.Bu sınır iki nedenle önemlidir:
Yaygın bir hata, “makbuzlar var” demenin “yönetiliyoruz” anlamına geldiğini varsaymaktır. Böyle değildir. Makbuzlar bir temel sağlar. Yönetim ise üzerine inşa edilen sistemdir.
Yukarıdaki madde 3 kendi bölümüne değer: bir işlem makbuzu “bu anahtar bu içeriği imzaladı” der, asla “bir insan yetkilendirdi” demez. Yüksek riskli işlemler (iade, silme, havale) için yönetim çerçeveleri tam olarak eksik olan bu ifadeyi giderek daha çok ister ve bu dersin öğrettiği aynı ilkelere dayanarak üretilebilir.
Takip defteri code_samples/human-authorization-receipts.ipynb, derste yaptığınız makbuzlarla aynı zarf biçiminde ikinci bir makbuz türü olan human.approval.v1 ekler (adı belirtilen onaylayıcı Ed25519 ile kanonik JCS baytlar üzerinden imzalar, signature nesnesi imzalanan baytların dışındadır). Onaylayan, tam kanonik eylemi ve özünü çalıştırmadan önce imzalar; ajanın işlem makbuzu aynı eylem özünü taşır ve bir parent_approval_ref (onay makbuzunun receipt_hashi), yukarıdaki zincirdeki previous_receipt_hash ile aynı konvansiyon uygulanır. Bir verify_chain her iki makbuzu da ayrı sabitlenmiş anahtar kayıtları altında doğrular (onaylayıcı anahtarlar vs ajan anahtarları), böylece kod yolu paylaşılsa da yetkililer asla paylaşılmaz.
Bu özelliğin dikkatle ifade edilen anlamı: insan bu tam eylemi onayladı ve ajan tam olarak onaylanan bu eylemi gerçekleştirdi. Defterdeki reddetme durumu, bu özelliği savunulan değil gerçek yapan şeydir:
Her başarısızlık farklı bir sebeple reddedilir; böylece bir denetçi reddi okurken otoritenin geçersizleşip geçersizleşmediğini veya yürütülen eylemin değişip değişmediğini anlayabilir. Defterin öğrettiği kural: imzalı onay tek başına otorite değildir. Otorite, her iki makbuz da yürütme zamanında aynı kanonik eyleme bağlıysa vardır. İnsan onay makbuzu bu ders tarafından tanımlanmış eğitsel bir bileşendir, draft-farley-acta-signed-receipts tarafından tanımlanan bir makbuz türü değildir.
Bu derste verilen Python kodu, her satırı okuyup tam olarak ne olduğunu anlayabilmeniz için kasıtlı olarak minimaldir. Üretimde iki seçeneğiniz vardır:
Doğrudan kriptografik ilkelere dayanarak inşa etmek. Yukarıda gördüğünüz 50 satır birçok kullanım durumu için yeterlidir. PyNaCl (Ed25519) ve jcs paketi (kanonik JSON) iyi bakılan ve denetlenen kütüphanelerdir.
Bir üretim makbuz kütüphanesi kullanmak. Birkaç açık kaynak proje, aynı modeli ek özelliklerle uygular (anahtar döndürme, toplu doğrulama, JWK Set dağıtımı, politika motorları ile entegrasyon):
draft-farley-acta-signed-receipts, revizyon 02) JCS ve imza kapsamı konvansiyonlarını kullanır. Bu dersin basit pedagojik makbuzu, taslakta {payload, signature} zarfından farklıdır ve uygun bir uygulama olarak sunulmamaktadır. Taslak, protokolüne uygunluk hedefleyen uygulamalar için paylaşılan bir uygunluk paketi yayınlar (agent-governance-testvectors).protect-mcp (npm) ve @veritasacta/verify (npm) paketleri, herhangi bir MCP sunucusunu tahrif fark edilir denetim izi ile sarmak için imzalama ve çevrimdışı doğrulama işlemlerinin Node tabanlı uygulamasını sağlar, durdurulmuş bir eylemin WebAuthn destekli onay makbuzu yayımladığı bir paylaşımlı onay akışı da dahil olmak üzere (masaüstü akışta), yukarıdaki insan onay defterindekiyle aynı onay-makbuz modeli.pip install nobulex), LangChain ve CrewAI entegrasyonlarıyla birlikte aynı Ed25519 + JCS imzalama modelini Python’da sağlar, yayınlanmış çapraz doğrulama test vektörleri ve OWASP PR #2210 aracılığıyla sağlanmış uygunluk eşlemesi içerir.Kendi çözümlerinizi oluşturmak veya bir kütüphane kullanmak kararları, kendi JWT kütüphanenizi yazmakla test edilmiş bir tane kullanmak arasındaki karara benzer: her ikisi de makul; kütüphane zaman kazandırır ve denetim yüzeyini azaltır; sıfırdan yaklaşım her ilkeyi anlamanızı sağlar. Bu ders sıfırdan yolu öğretir, böylece her iki seçeneğin temelini görürsünüz.
Uygulama egzersizine geçmeden önce anlayışınızı test edin.
1. Bir makbuz ajan özel Ed25519 anahtarı ile imzalanır. Denetçinin yalnızca genel anahtarı vardır. Denetçi makbuzu çevrimdışı doğrulayabilir mi?
2. Bir saldırgan, bir makbuzun policy_id alanını daha izin verici bir politika ile yönetildiğini iddia edecek şekilde değiştirir. İmza orijinal yük üzerinde yapılmıştır. Doğrulama sırasında ne olur?
3. Makbuzda neden ham argümanlar ve sonuç yerine tool_args_hash ve result_hash bulunuyor?
4. previous_receipt_hash alanı her makbuzu bir önceki makbuza bağlar. Bir saldırgan zincirin ortasından bir makbuzu sessizce silerse, ne geçersiz olur?
5. Bir makbuz başarıyla doğrulanırsa, bu temsilcinin eyleminin doğru, sağlam veya politika ile uyumlu olduğunu kanıtlar mı?
code_samples/18-signed-receipts.ipynb dosyasını açın ve dört bölümü tamamlayın:
Gelişmiş meydan okuma 1: Makbuz şemasını kendi seçeceğiniz ek bir alanla genişletin (örneğin izleme için bir istek kimliği), kanonik imzalama mantığını bunu da dahil edecek şekilde güncelleyin ve makbuzun doğrulamada hâlâ sorunsuz işlem gördüğünü onaylayın. Daha sonra imzalamadan sonra alanı değiştirin ve doğrulamanın başarısız olduğunu doğrulayın. Bu, kanonik kodlamadaki her baytın imzaya nasıl katkıda bulunduğunu anlamanızı sağlar.
Gelişmiş meydan okuma 2: İki makbuzunuzun kanonik baytlarını belirli bir sırayla birleştirip SHA-256 ile hashleyin ve oluşan özet değerini imzalamadan önce üçüncü bir makbuza yeni bir alan olarak gömün. Üç makbuzun da sorunsuz doğrulandığını test edin. Böylece bir adımlı içerme kanıtı oluşturmuş olursunuz: üçüncü makbuzu elinde tutan herkes, ilk iki makbuzun imza anında var olduğunu kanıtlayabilir, içeriklerini açığa çıkarmadan. Bu, seçmeli açıklama makbuzlarının büyük ölçekte kullandığı desen (Merkle taahhütleri, RFC 6962).
Kriptografik makbuzlar, AI temsilcilerine şu özellikleri sağlayan bir denetim izi verir:
Girdi doğrulama, politika uygulaması veya kimlik altyapısı yerine geçmezler. Bu katmanlar için bir temel oluştururlar. Temsilcileri düzenlenmiş iş yüklerine, çoklu organizasyon iş akışlarına veya gelecekte bir denetçinin size güvenemeyeceği ortamlara dağıtırken, makbuzlar denetim izini dürüst yapmanın yoludur.
En önemli mesaj: makbuzlar kim, ne zaman ne dediği kanıtlar. Söylenenin doğru veya doğru olduğunu kanıtlamaz. Bu farkı sıkı tutun. Dürüst bir köken sistemi ile yanıltıcı bir sistem arasındaki fark budur.
Bu dersten gerçek bir ortamda makbuz-imzalı temsilciler dağıtmaya geçmeye hazır olduğunuzda:
https://your-org.example.com/.well-known/agent-keys.json.Diğer öğrenenlerle tanışmak, ofis saatlerine katılmak ve AI Temsilcileri ile ilgili sorularınızı sormak için Microsoft Foundry Discord sunucusuna katılın.
Bu ders tek makbuz imzalama ve hash zincirli dizileri kapsar. Aynı temel yapı taşları, yönetim duruşunuz geliştikçe karşılaşabileceğiniz daha gelişmiş desenler oluşturur:
authorization_*) ve yürütme sonrası (result_*) yarılara böler ve bağımsız imzalarla imzalar. Yetkilendirme kararı ve gözlemlenen sonuç farklı aktörlerce veya zamanlarda üretiliyorsa faydalıdır. Bu, bu derste öğretilen makbuz formatının üstüne eklenebilir.result_hash içine koyduğunuz baytları mühürler. Gerçek dünya yükleri genellikle tek bir araç çağrısı sonucundan daha zengindir: karar öncesi gerekçeler (model tahmini, düşünülen seçenekler, kanıt ve tamamlık durumu, risk duruşu, hesap verebilirlik zinciri, geçiş sonucu) tümü bir makbuzda mühürlenebilir. Bu, makbuz formatını minimal tutarken alan şemalarının alan bazında gelişmesini sağlar.signature.alg alanı, ihtiyaç duyduğunuzda ML-DSA-65 (NIST kuantum sonrası imza standardı) taşıyabilir. Geçiş dönemi için makbuzlar çift imzalı olabilir.Yerel AI Temsilcileri Oluşturma
Feragatname: Bu belge, AI çeviri hizmeti Co-op Translator kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalardan veya yanlış yorumlamalardan sorumlu değiliz.