Mandate Ledger para el comercio de agentes de confianza en MongoDB

Establecer confianza con AP2

El Protocolo de Pagos para Agentes de Google2 (AP) proporciona un protocolo abierto, seguro e interoperable que crea un ecosistema de confianza para comerciantes, instituciones financieras y clientes cotidianos.

Figura 1. La capa de confianza

AP2 protege las transacciones a través de credenciales digitales verificables (VDC), cargas útiles de JSON criptográficamente firmadas y a prueba de manipulaciones que los agentes crean e intercambian. AP2 clasifica estas VDC en tres mandatos principales:

• El mandato de intención: describe lo que el cliente requiere y define las condiciones bajo las cuales un agente de IA puede realizar una compra en nombre del cliente.

• El mandato del carrito: Proporciona un recibo digital firmado tanto por el comerciante como por el cliente para autorizar compras con presencia humana.

• El mandato de pago: crea una capa de visibilidad compartida directamente con la red de pago para señalar de forma segura la participación del agente de IA.

Los VDC actúan como contratos digitales permanentes. Los agentes firman criptográficamente estas cargas útiles para capturar la intención del cliente. Este proceso crea una pista no repudiable para auditar para cada paso de la experiencia de compra.

Figura 2. Una conversación contractual con pruebas verificables en cada paso

Figura 3. Visualización de intenciones en la interfaz de usuario, que muestra cómo se representa cada intención dentro de la conversación

Garantice la responsabilidad con MongoDB Atlas

Para que estos VDC criptográficos sigan siendo fiables, los sistemas deben almacenarlos en un entorno seguro y verificable. El servicio Mandate Ledger actúa como middleware de protección entre los agentes de IA y la base de datos. Detrás de este middleware se encuentra MongoDB Atlas.

Atlas proporciona la seguridad de nivel empresarial diseñada para admitir una pista de auditar a prueba de manipulaciones. Compile esta arquitectura para crear la capa de confianza inmutable, el servicio de libro mayor de mandatos, necesario para escalar el comercio agente seguro.

Imagine a un cliente pidiéndole a un asistente de IA que compre un nuevo teléfono inteligente. El agente de compras negocia de forma autónoma con los comerciantes para encontrar la oferta perfecta. El servicio de libro mayor de mandatos registra todo este recorrido empaquetando cada solicitud, aprobación y paso de pago en mandatos JSON firmados criptográficamente. MongoDB Atlas almacena cada mandato como un documento inmutable. Este proceso transforma un simple chat en una prueba de intención permanente e irrefutable.

Esta solución muestra cómo compilar el servicio de libro mayor de mandatos sobre una arquitectura que utiliza el protocolo AP2.

El Ledger Service: un escudo protector

El servicio de contabilidad de mandatos actúa como un middleware de protección que conecta al agente comercial con la base de datos. Compila este servicio con FastAPI o gRPC.

Figura 5. Arquitectura detallada del servicio de contabilidad de mandatos

Procese todas las solicitudes de agente a través de tres capas seguras y distintas:

• La capa de autenticación: valida las claves API para identificar de forma segura a los agentes. Aplica el control de acceso basado en roles (RBAC) por tipo de agente para aplicar permisos estrictos de agente.

• La capa de lógica empresarial: ejecuta la validación de solicitudes principales y el control de concurrencia. Aplica la idempotencia para reintentos de red seguros y admite la inmutabilidad estricta del mandato.

• La capa de acceso a los datos: utiliza el cliente de MongoDB y la indexación optimizada para ejecutar operaciones de base de datos. Esta capa define el campo _id como inmutable y bloquea todas las operaciones de actualizar y borrar a través de la validación de esquema.

La cadena de mandatos: del intento al pago

Cada transacción de AP2 avanza a través de una secuencia estructurada de mandatos firmados criptográficamente. Cada paso produce un registro inmutable en MongoDB Atlas, creando una pista de auditoría completa desde la intención hasta el pago.

Figura 6. Flujo de datos

Para mover una transacción de la intención al pago, los agentes de AP2 completan la siguiente secuencia de transacciones:

1. Capture la intención del cliente. El agente de compras traduce la solicitud del cliente, como una descripción en lenguaje natural de "zapatillas de correr", en un mandato de intención estructurado. El mandato de intención captura el comerciante objetivo, los requisitos de reembolsabilidad, las preferencias de confirmación del carrito y una ventana de vencimiento. El agente de compras firma el mandato utilizando EdDSA en nombre del cliente y lo envía al agente comercial con un estado de signed y un hash de versión que bloquea su contenido.

2. Almacene el mandato de intención. El agente comercial guarda el mandato de intención en Atlas a través del servicio de libro mayor de mandatos. El servicio de libro mayor valida la solicitud, aplica el control de acceso basado en roles y anexa el registro de forma inmutable.

3. Cree el mandato del carrito. El agente comercial compila una oferta de carrito que contiene todos los detalles del producto: nombre del artículo, precio, divisa, métodos de pago aceptados y fecha de caducidad. El agente comercial lo almacena en Atlas a través del servicio de libro mayor de mandatos, donde el registro recibe un estado de proposed y una encriptada de versión para garantizar la integridad.

4. Ofrezca el carrito al cliente. El agente comercial devuelve el mandato de carrito propuesto al agente de compras, que presenta las opciones de productos disponibles al cliente.

5. Acepte el mandato del carrito. El cliente selecciona una opción. El agente de compras cofirma el mandato del carrito en nombre del cliente utilizando una clave de dispositivo respaldada por hardware y envía el mandato aceptado de vuelta al agente comercial.

6. Refrende y finalice el mandato del carrito. El agente comercial añade su firma criptográfica al carrito aceptado y almacena el mandato del carrito totalmente firmado por dos partes en Atlas, bloqueando los términos acordados con un estado signed.

7. Cree el mandato de pago. El agente de compras query al proveedor de credenciales para recuperar el token de pago adecuado. A continuación, el agente de compras crea y firma el mandato de pago en nombre del cliente y lo envía al agente comercial. El proveedor de credenciales nunca devuelve números de tarjeta de crédito completos, lo que garantiza que el agente de compras nunca acceda a datos sin procesar.

8. Almacenar el mandato de pago. El agente comercial guarda el mandato de pago firmado en Atlas a través del servicio de libro mayor de mandatos. El servicio de libro mayor comparte este mandato directamente con las instituciones financieras para marcar la participación del agente de IA, y el procesador de pagos utiliza este mandato para enrutar la autorización a la red de pagos.

Los agentes no pueden modificar ni borrar registros existentes. MongoDB Atlas aplica guardar de solo anexar, por lo que la cadena de mandatos completa —Intención, Carrito y Pago— permanece intacta y puede ser verificada de forma independiente por el agente de auditoría en cualquier momento.

El libro mayor de mandatos: un almacén polimórfico para almacenar documentos

La colección mandate_ledger almacena los tres tipos de mandatos en una sola colección. Utiliza el campo entity_type para distinguirlos en el momento de la query, lo que elimina la necesidad de uniones o colecciones separadas por tipo de mandato.

Todos los documentos comparten una estructura de sobre común:

{
  "entity_id": "IntentMandate_955181ea-11c3-4379-92c4-3e27c5f278d3",
  "entity_type": "IntentMandate",
  "version": 1,
  "status": "signed",
  "transaction_id": "txn_fca7db66-c769-4206-b891-7140af37f8f4",
  "user_id": "hunter-d53910cf-b9e2-4876-8668-8251c990e203",
  "created_by_agent": "merchant_agent_dev",
  "created_by_agent_type": "merchant-agent",
  "current_version_hash": "4a822a01468a27dfd...",
  "signatures": [...],
  "mandate_data": { ... }
}

El campo mandate_data contiene la carga útil específica del tipo, donde cada tipo de mandato almacena una estructura de datos diferente:

"mandate_data": {
  "natural_language_description": "cheapest french press coffee maker",
  "merchants": [],
  "skus": [],
  "requires_refundability": true,
  "user_cart_confirmation_required": true,
  "intent_expiry": "2026-04-18T20:00:03.651746+00:00"
}

"mandate_data": {
  "contents": {
    "payment_request": {
      "method_data": [{ "supported_methods": "CARD", "data": { "network": ["mastercard", "paypal", "amex"] }}],
      "details": {
        "display_items": [
          { "label": "Standard Laptop", "amount": { "currency": "USD", "value": 1203.50 }, "refund_period": 30 },
          { "label": "Shipping", "amount": { "currency": "USD", "value": 2.00 }},
          { "label": "Tax", "amount": { "currency": "USD", "value": 1.50 }}
        ],
        "total": { "label": "Total", "amount": { "currency": "USD", "value": 1203.50 }}
      }
    },
    "shipping_address": { "recipient": "Bugs Bunny", "address_line": ["123 Main St"], "city": "Sample City", "country": "US" },
    "cart_expiry": "2026-04-17T20:29:05.197984+00:00"
  },
  "merchant_authorization": "eyJhbGciOiJSUzI1NiIs..."
}

"signatures": [
  { "signer_type": "shopping-agent", "algorithm": "EdDSA", "signed_at": "2026-04-17T19:59:49Z" },
  { "signer_type": "merchant-agent", "algorithm": "JWT",   "signed_at": "2026-04-17T19:59:50Z" }
]

"mandate_data": {
  "payment_mandate_contents": {
    "payment_details_total": { "label": "Total", "amount": { "currency": "USD", "value": 1203.50 }},
    "payment_response": {
      "method_name": "CARD",
      "details": { "token": { "value": "fake_payment_credential_token_5" }},
      "shipping_address": { "recipient": "Bugs Bunny", "address_line": ["123 Main St"], "city": "Sample City" },
      "payer_email": "bugsbunny@gmail.com"
    },
    "merchant_agent": "Generic Merchant",
    "timestamp": "2026-04-17T20:00:22.603453+00:00"
  },
  "user_authorization": "fake_cart_mandate_hash_cart_fb1b4c86..._fake_payment_mandate_hash_812843b2..."
}

Pagos: El registro de finalización ultraligero

La payments colección almacena un documento por cada transacción completada. Esta colección aplica el patrón de referencia extendida.

En lugar de la incrustación del contenido completo del mandato, cada documento almacena solo el ID del mandato y la firma autorizada para cada uno de los tres mandatos. Este diseño mantiene el registro de pagos pequeño y rápido de leer, al tiempo que conserva un puntero directo a los datos completos en la colección mandate_ledger cuando se requiere un seguimiento completo para auditar.

{
  "payment_id": "pay_123c25ac-7b56-4e45-8dd1-30cdcda944c7",
  "transaction_id": "txn_6fbab918-2b5d-4ddd-89d8-fdb96e5648d9",
  "user_id": "hunter-263b752e-92be-4001-ab9d-38847811c663",
  "intent_mandate":  { "mandate_id": "IntentMandate_41bbeacf-...",  "signature": "0x_shopping_agent_sig_...", "timestamp": "2026-04-15T19:50:57Z" },
  "cart_mandate":    { "mandate_id": "CartMandate_c0e8f369-...",    "signature": "eyJhbGciOiJSUzI1NiIs...",  "timestamp": "2026-04-15T19:52:07Z" },
  "payment_mandate": { "mandate_id": "PaymentMandate_33c39b8c-...", "signature": "fake_cart_mandate_hash_...", "timestamp": "2026-04-15T19:53:53Z" },
  "amount": 28,
  "currency": "USD",
  "status": "SUCCESS",
  "payment_method_type": "CARD",
  "merchant_agent": "merchant_agent_dev",
  "payment_processor_agent": "payment_processor",
  "processed_at": "2026-04-15T19:54:14Z"
}

Este diseño mantiene intencionalmente el documento pequeño. Los términos completos, las partidas y las pruebas criptográficas residen en la colección mandate_ledger. El registro de pago solo existe para confirmar que la transacción está completa y para proporcionar los tres punteros necesarios para reconstruir la cadena de auditar completa. Utilice el campo transaction_id para unirse a ambas colecciones cuando se requiera un seguimiento completo.

Claves de API: identificación segura del agente

La colección api_keys gestionado/gestionada las claves API para identificar de forma segura a los agentes. Utilice esta colección para almacenar las claves asociadas con cada agente que llama al servicio.

Registro de auditoría: la ruta operativa

La colección audit_log almacena todas las operaciones de la API para el cumplimiento y la depuración. Utilice esta colección para registrar eventos a nivel de servicio, como la creación de mandatos, los intentos de acceso y los resultados de la validación. Este enfoque evita la expansión del propio libro mayor de mandatos inmutable. Agregue un índice TTL para remover automáticamente los registros después de 90 días. Esto conserva un rastro operativo útil mientras mantiene la colección limitada.

La colección incluye los siguientes campos clave:

• event_type: Identifica el tipo de operación, como mandate.created.

• entity_id: Hace referencia al mandato relacionado.

• actor_agent_id: captura qué agente realizó la acción.

• event_timestamp: Registra cuándo ocurrió el evento y admite la política de TTL.

• expires_at: Define cuándo MongoDB borra automáticamente el registro.

Registros de idempotencia: gestión segura de reintentos

La colección idempotency_records almacena claves de idempotencia para evitar operaciones duplicadas. Utilice esta colección para retener la clave proporcionada por el cliente, el agente que realizó la solicitud y la entrada del libro mayor creada para esa operación. Agregue un índice TTL para remover automáticamente los registros después de 24 horas.

La colección incluye los siguientes campos clave:

• idempotency_key: Almacena la clave única proporcionada por el cliente y requiere un índice.

• agent_id: Identifica al agente que realizó la solicitud.

• ledger_entry_id: Hace referencia al mandato creado para la solicitud original.

• expires_at: Define cuándo MongoDB borra automáticamente el registro.

Requisitos previos

Antes de comenzar, asegúrese de instalar y configurar lo siguiente:

• MongoDB Atlas o MongoDB autogestionado 7.0 o posterior

• Python 3.13 (versión 3.13.x)

• uv para la gestión de dependencias

• Una clave API de Google o acceso a Vertex AI

• Docker para ejecutar servicios como contenedores

• Node.js y npm para la aplicación frontend

Procedimiento