Ver el video de la lección: Asegurando agentes de IA con recibos criptográficos
(El video de la lección y la miniatura serán añadidos por el equipo de contenido de Microsoft después de la fusión, siguiendo el patrón de la lección 14 / 15.)
Esta lección cubrirá:
Al completar esta lección, sabrás cómo:
Imagina que has desplegado un agente de IA para Contoso Travel. El agente lee solicitudes de clientes, llama a una API de vuelos para buscar opciones y reserva asientos en nombre del cliente. El último trimestre, el agente procesó 50,000 reservas.
Hoy llega un auditor. Hace una pregunta simple: “Muéstrame qué hizo tu agente.”
Le entregas tus archivos de registro. El auditor los revisa y hace la pregunta más difícil: “¿Cómo sé que estos registros no fueron editados?”
Este es el problema del rastro de auditoría. La mayoría de los despliegues de agentes hoy dependen de:
Ninguno de estos puede responder a la pregunta del auditor sin que el auditor tenga que confiar en alguien (tú, tu proveedor de nube, tu proveedor de base de datos). Para uso interno, esa confianza suele ser aceptable. Para cargas reguladas (finanzas, salud, cualquier cosa sujeta al Acta de IA de la UE), no lo es.
Los recibos criptográficos reducen este problema al hacer que una declaración firmada independientemente verificable. El auditor todavía necesita una razón fuera de banda para confiar en la clave de firma y el componente que produjo la declaración. Una clave incrustada demuestra la autoconsistencia, no la identidad del emisor ni el lugar donde se hace cumplir.
Un recibo es un objeto JSON que registra lo que hizo un agente, firmado con una firma digital.
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]
Un recibo minimalista se ve así:
{
"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..."
}
}
Tres propiedades están haciendo el trabajo:
La firma. El recibo está firmado por la pasarela del agente usando una clave privada Ed25519. Cualquier persona con la clave pública correspondiente puede verificar la firma sin conexión. Una parte que confía debe fijar esa clave o resolverla desde un registro de confianza fuera del recibo. La manipulación de cualquier campo firmado invalida la firma.
Codificación canónica. Antes de firmar, el recibo se serializa usando JSON Canonicalization Scheme (JCS, RFC 8785). Esto asegura que dos implementaciones que produzcan el mismo recibo lógico produzcan salida idéntica byte a byte. Sin canonicalización, diferentes serializadores JSON producirían firmas distintas para el mismo contenido.
Encadenamiento de hashes. El campo previous_receipt_hash enlaza cada recibo con el anterior. Eliminar o reordenar un recibo rompe la secuencia presentada. Detectar un truncamiento o una reescritura controlada por el firmante también requiere una cabeza de la cadena actual fijada, un punto de control atestiguado de forma independiente o un compromiso autenticado de población cerrada.
Juntas estas propiedades proveen tres garantías:
No necesitas una biblioteca especial para producir un recibo. Los primitivos criptográficos están ampliamente disponibles y la lógica es unas pocas docenas de líneas en Python.
Los ejercicios prácticos en code_samples/18-signed-receipts.ipynb recorren todo el flujo. El code_samples/18-signed-receipts.execution-receipt.json bajo control de versiones registra el hash exacto del cuaderno, el entorno de Python, el número de celdas y las comprobaciones de la última ejecución limpia sin cambiar los resultados guardados de la lección. La versión resumida:
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)),
},
}
Esa es toda la línea de firma. Los ejercicios en el notebook explican cada paso.
La verificación es la operación inversa:
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
Esta función toma un recibo más el conjunto de claves fijadas de la parte confiada y devuelve
True solo si la firma es válida con una clave aceptada. La verificación no requiere
llamada a la red, pero la confianza en la clave sigue siendo una decisión de configuración externa.
Para ver la detección de manipulación en acción, el notebook muestra:
tool_args_hash.Esta es la demostración práctica de que los recibos son evidentes en cuanto a manipulaciones: cualquier modificación, por pequeña que sea, rompe la firma.
Un recibo firmado protege una acción. Una cadena de recibos protege una secuencia.
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
Cada recibo registra el hash del recibo anterior. Para eliminar silenciosamente el recibo 2, un atacante necesitaría:
previous_receipt_hash del recibo 3 (rompe la firma del recibo 3), OSi la clave privada está protegida y un verificador ancla la cabecera de una cadena atestiguada de forma independiente estos ataques son detectables. Publicar la clave dentro de cada recibo no es suficiente: un firmante o atacante puede presentar una clave diferente, reescribir un sufijo, o truncar la cadena a menos que la parte que confía tenga una ancla externa de confianza y de completitud.
El notebook muestra:
previous_receipt_hash de cada recibo coincida con el hash real del recibo previo.Así es como se produce un registro de auditoría que un auditor externo puede verificar bajo sus propias claves del emisor fijadas y puntos de control de la cadena, sin confiar en su almacén de registros mutable.
Esta es la sección más importante de esta lección. Los recibos son poderosos pero su poder es limitado.
Los recibos prueban tres cosas:
Los recibos NO prueban:
policy_id fue realmente evaluada, o que hubiera permitido esta acción si se hubiera verificado. El recibo registra lo que se dijo, no lo que se hizo cumplir.Este límite importa por dos razones:
Un error común es suponer que “tenemos recibos” significa “estamos gobernados”. No es así. Los recibos son una base. La gobernanza es el sistema que construyes encima.
El punto 3 anterior merece su propia sección: un recibo de acción dice “esta clave firmó este contenido”, nunca “un humano autorizó esto.” Para acciones de alto riesgo (reembolsos, eliminaciones, transferencias bancarias), una firma aprobadora separada puede vincular la acción exacta. Conectar esa clave a un humano y comprobar la presencia humana siguen siendo responsabilidades separadas.
El cuaderno de seguimiento code_samples/human-authorization-receipts.ipynb añade un segundo tipo de recibo, human.approval.v1, en la misma forma de sobre que los recibos de la lección (una carga tipada firmada por Ed25519 sobre sus bytes canónicos JCS, con el objeto signature fuera de los bytes firmados). Una clave de aprobador firma la acción canónica completa y su digest; una clave de agente firma una reclamación que porta el mismo digest de acción y un parent_approval_ref, el receipt_hash de la aprobación, la misma convención que previous_receipt_hash en la cadena que construiste arriba. Un verify_chain recorre ambos artefactos bajo registros de claves fijados separados (claves de aprobador vs claves de agente), de modo que la ruta de código se comparte pero las autoridades nunca lo hacen.
La propiedad que esto confiere, enunciada cuidadosamente: la clave del aprobador fijada firmó esta exacta acción, y la clave del agente posteriormente firmó una declaración que contiene el mismo resumen de la acción. Eso es evidencia útil, pero no es por sí sola prueba de que la acción se ejecutó. Para controlar la ejecución, la aprobación exacta también debe reservarse y consumirse una vez en el límite del ejecutor real; los resultados desconocidos del proveedor deben permanecer desconocidos en lugar de reintentarlos a ciegas. Los fixtures de rechazo del cuaderno prueban la capa de cadena de recibos:
Cada rechazo incluye una razón distinta, de modo que un auditor que lea un rechazo puede saber si la autoridad quedó obsoleta o si la acción reclamada cambió. La verificación es de solo lectura y repetible: no consume la aprobación ni invoca a un proveedor. Un ejecutor separado necesita protección duradera y atómica contra la reproducción y resultados explícitos de éxito, fallo e indeterminados. El recibo de aprobación humana es una composición educativa definida por esta lección, no un tipo de recibo definido por draft-farley-acta-signed-receipts.
El código Python en esta lección es intencionalmente minimalista para que puedas leer cada línea y entender exactamente qué sucede. En producción, tienes dos opciones:
Construir directamente sobre los primitivos criptográficos. Las 50 líneas que viste arriba son suficientes para muchos casos de uso. PyNaCl (Ed25519) y el paquete jcs (JSON canónico) son bibliotecas bien mantenidas y auditadas.
Usar una biblioteca de recibos para producción. Varios proyectos de código abierto implementan el mismo patrón con características adicionales (rotación de claves, verificación en lote, distribución JWK Set, integración con motores de políticas):
draft-farley-acta-signed-receipts, revisión 02). El recibo plano educativo de esta lección difiere del sobre {payload, signature} del borrador y no se presenta como una implementación conforme. El borrador publica una suite de conformidad compartida (agent-governance-testvectors) para implementaciones dirigidas a su formato wire.protect-mcp (npm) y @veritasacta/verify (npm) proporcionan una implementación basada en Node para firma de recibos y verificación sin conexión, destinada a envolver cualquier servidor MCP con un rastro de auditoría evidente de manipulaciones, incluyendo un flujo de co-firma retenido en el que una acción pausada emite un recibo de aprobación vinculado al digest de la acción (respaldado por WebAuthn en el flujo de escritorio), el mismo patrón de recibo de aprobación del notebook de autorización humana arriba.pip install nobulex) proporciona el mismo patrón de firma Ed25519 + JCS en Python con integraciones LangChain y CrewAI, incluyendo vectores de prueba de validación cruzada publicados y un mapeo de cumplimiento aportado vía OWASP PR #2210.
- EMILIA Protocol proporciona una capa complementaria de aplicación de acciones exactas: recibos de aprobación verificables sin conexión, WebAuthn fijado o autoridad de quórum, consumo único en el límite del ejecutor, y una ruta explícita de resultado indeterminado. Sus adaptadores del framework tratan un recibo como evidencia necesaria en lugar de prueba de que ocurrió un efecto externo.La decisión entre crear tu propia solución y usar una biblioteca es similar a la decisión entre escribir tu propia biblioteca JWT o usar una probada: ambas son razonables; la biblioteca ahorra tiempo y reduce la superficie de auditoría; el enfoque desde cero te obliga a entender cada primitivo. Esta lección enseña el camino desde cero para que tengas la base para cualquiera de las opciones.
Pon a prueba tu comprensión antes de pasar al ejercicio práctico.
1. Un recibo está firmado con la clave privada Ed25519 del agente. El auditor tiene solo la clave pública. ¿Puede el auditor verificar el recibo sin conexión?
2. Un atacante modifica el campo policy_id de un recibo para afirmar que estuvo gobernado por una política más permisiva. La firma fue sobre la carga original. ¿Qué ocurre durante la verificación?
3. ¿Por qué el recibo incluye un tool_args_hash y result_hash en lugar de los argumentos y resultados en bruto?
4. El campo previous_receipt_hash enlaza cada recibo con su predecesor. Si un atacante elimina silenciosamente un recibo del medio de una cadena, ¿qué se vuelve inválido?
5. Un recibo se verifica correctamente. ¿Eso prueba que la acción del agente fue correcta, válida o conforme a la política?
Abre code_samples/18-signed-receipts.ipynb y completa las cuatro secciones:
Desafío adicional 1: extiende el esquema del recibo con un campo adicional de tu elección (por ejemplo, un ID de solicitud para rastreo), actualiza la lógica canónica de firma para incluirlo y confirma que el recibo aún puede verificarse correctamente. Luego modifica el campo después de firmar y confirma que la verificación falla. Esto te obliga a entender cómo cada byte de la codificación canónica contribuye a la firma.
Desafío adicional 2: Haz un hash SHA-256 combinando dos de tus recibos (concatena sus bytes canónicos en un orden determinista) y embebe el resumen resultante como un nuevo campo en un tercer recibo antes de firmarlo. Verifica que los tres recibos aún pueden verificarse. Has construido una prueba de inclusión de un paso: cualquiera con el tercer recibo puede probar que los dos primeros existían en el momento de la firma, sin revelar su contenido. Este es el patrón que usan los recibos de divulgación selectiva a escala (compromisos de Merkle, RFC 6962).
Los recibos criptográficos dan a los agentes de IA una pista de auditoría que es:
No son un sustituto de la validación de entradas, la aplicación de políticas, la admisión de ejecutores, evidencia de resultados, controles de completitud, o la infraestructura de identidad. Son una base para esas capas. En flujos de trabajo regulados o multi-organización, los comprobantes hacen que las declaraciones específicas del emisor sean verificables de forma independiente bajo la propia configuración de confianza del auditor.
La conclusión más importante: los recibos demuestran que una clave en particular firmó contenido particular. Una marca de tiempo incorporada es una afirmación del firmante a menos que esté atestiguada por separado. Un recibo no prueba que su contenido fuera verdadero, que una acción se ejecutó, o que el conjunto de registros esté completo. Mantén esas distinciones con rigor.
Cuando estés listo para pasar de esta lección a desplegar agentes con recibos firmados en un entorno real:
Únete al Microsoft Foundry Discord para conectar con otros estudiantes, asistir a horas de oficina y resolver tus preguntas sobre agentes de IA.
Esta lección cubre la firma de recibos simples y secuencias encadenadas con hashes. Las mismas primitivas se combinan en varios patrones más avanzados que puedes encontrar a medida que madura tu postura de gobernanza:
authorization_*) y post-ejecución (result_*) con firmas independientes, útil cuando la decisión de autorización y el resultado observado son producidos por actores distintos o en tiempos distintos. Esto se suma al formato de recibo enseñado en esta lección.result_hash. Las cargas reales suelen ser más ricas que un solo resultado de llamada a herramienta: el razonamiento previo a la decisión (predicción del modelo, opciones consideradas, evidencia y su completitud, postura de riesgo, cadena de responsabilidad, resultado de puerta) puede vivir dentro de la carga sellada por un solo recibo. Esto mantiene el formato de recibo minimalista mientras permite que los esquemas de carga evolucionen dominio por dominio.alg por sí sola no es una migración: un perfil debe definir la codificación de clave ML-DSA, los bytes firmados canónicos, la verificación, la política de la parte que confía, la resistencia a retrocesos y la semántica de transición. Planifique y pruebe una transición con firma dual contra vectores compartidos antes de hacer declaraciones de compatibilidad.Descargo de responsabilidad: Este documento ha sido traducido utilizando el servicio de traducción automática Co-op Translator. Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No somos responsables de cualquier malentendido o interpretación errónea que surja del uso de esta traducción.