Libro mayor de mandatos para comercio agente confiable 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 mediante Credenciales Digitales Verificables (VDC), cargas útiles JSON firmadas criptográficamente 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 las compras realizadas en presencia del comprador.

• El mandato de pago: Crea una capa de visibilidad compartida directamente con la red de pagos para indicar de forma segura la participación de un agente de IA.

Los VDC funcionan como contratos digitales permanentes. Los agentes firman criptográficamente estas cargas útiles para capturar la intención del cliente. Este proceso crea un registro de auditoría irrefutable para cada paso de la experiencia de compra.

Figura 2. Una conversación contractual con prueba verificable en cada paso.

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

Garantice la rendición de cuentas con MongoDB Atlas

Para que estos VDC criptográficos sigan siendo fiables, los sistemas deben almacenarlos en un entorno seguro y verificable. El Servicio de Libro Mayor de Mandatos 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 seguridad de nivel empresarial diseñada para admitir un registro de auditoría a prueba de manipulaciones. Cree esta arquitectura para desarrollar la capa de confianza inmutable, el Servicio de Libro Mayor de Mandatos, necesaria para escalar el comercio seguro entre agentes.

Imagina a un cliente pidiéndole a un asistente de IA que le compre un nuevo smartphone. El agente de compras negocia de forma autónoma con los comercios para encontrar la mejor oferta. El servicio Mandate Ledger registra todo este proceso, 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 una simple conversación en una prueba de intención permanente e irrefutable.

Esta solución muestra cómo construir el Servicio de Libro Mayor de Mandatos sobre una arquitectura que utiliza el protocolo AP2.

El Servicio de Libro Mayor: Un Escudo Protector

El servicio Mandate Ledger actúa como un middleware de protección que conecta al agente comercial con la base de datos. Desarrolle este servicio utilizando FastAPI o gRPC.

Figura 5. Arquitectura detallada del servicio de registro de mandatos

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

• 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) según el tipo de agente para garantizar permisos estrictos para los agentes.

• La capa de lógica de negocio: Ejecuta la validación de solicitudes principales y el control de concurrencia. Garantiza la idempotencia para reintentos de red seguros y admite la inmutabilidad estricta de los mandatos.

• Capa de acceso a datos: Utiliza el cliente de MongoDB y la indexación optimizada para ejecutar operaciones de base de datos. Esta capa define el _id campo como inmutable y bloquea todas las operaciones de actualización y eliminación mediante la validación del esquema.

La cadena de mandatos: desde la intención hasta el pago.

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

Figura 6. Flujo de datos

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

1. Captura la intención del cliente. El Agente de Compras traduce la solicitud del cliente, como una descripción en lenguaje natural de "zapatillas para correr", en un Mandato de Intención estructurado. El Mandato de Intención captura el comercio objetivo, los requisitos de reembolso, las preferencias de confirmación del carrito y un plazo de caducidad. El Agente de Compras firma el mandato usando EdDSA en nombre del cliente y lo envía al Agente del Comercio 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 escribe el Mandato de Intención en Atlas a través del Servicio de Registro de Mandatos. El servicio de registro valida la solicitud, aplica el Control de Acceso Basado en Reglas (RBAC) y agrega el registro de forma inmutable.

3. Cree el mandato del carrito. El agente comercial crea una oferta de carrito con todos los detalles del producto: nombre del artículo, precio, moneda, métodos de pago aceptados y fecha de vencimiento. A continuación, el agente comercial la almacena en Atlas a través del servicio de registro de mandatos, donde el registro recibe un estado de proposed y un hash de versión para garantizar su integridad.

4. Ofrezca el carrito al cliente. El agente comercial devuelve la orden de compra propuesta 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 firma conjuntamente el mandato del carrito en nombre del cliente mediante una llave de dispositivo con respaldo de hardware y envía el mandato aceptado de vuelta al agente del comercio.

6. Refrenda y finalice el mandato del carrito. El agente comercial agrega su firma criptográfica al carrito aceptado y almacena el mandato del carrito con doble firma en Atlas, bloqueando los términos acordados con un signed estado.

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

8. Almacene el mandato de pago. El agente comercial envía el mandato de pago firmado a Atlas a través del servicio de registro de mandatos. Este servicio comparte dicho mandato directamente con las instituciones financieras para indicar la participación del agente de IA, y el procesador de pagos utiliza este mandato para enviar la autorización a la red de pagos.

Los agentes no pueden modificar ni eliminar registros existentes. MongoDB Atlas aplica escrituras de solo adición, por lo que la cadena completa de mandatos (Intención, Carrito y Pago) permanece intacta y el Agente Auditor puede verificarla de forma independiente en cualquier momento.

El Libro Mayor de Mandatos: Un Almacén de Documentos Polimórfico

La colección mandate_ledger almacena los tres tipos de mandato en una sola colección. Utilice el campo entity_type para distinguirlos en el momento de la consulta, lo que elimina la necesidad de uniones o colecciones separadas para cada 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 incluir el contenido completo del mandato, cada documento almacena únicamente el ID del mandato y la firma de autorización para cada uno de los tres mandatos. Este diseño permite que el registro de pago sea pequeño y de lectura rápida, a la vez que conserva un puntero directo a los datos completos en la colección mandate_ledger cuando se requiere un seguimiento de auditoría completo.

{
  "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 busca mantener el documento pequeño intencionadamente. Los términos completos, las partidas y las pruebas criptográficas se encuentran en la colección mandate_ledger. El registro de pago solo sirve para confirmar que la transacción se ha completado y para proporcionar los tres punteros necesarios para reconstruir la cadena de auditoría completa. Utilice el campo transaction_id para combinar ambas colecciones cuando se requiera un seguimiento completo.

Claves API: Identificación segura de agentes

La colección api_keys gestiona las claves API para identificar de forma segura a los agentes. Utilice esta colección para almacenar las claves asociadas a cada agente que llame al servicio.

Registro de auditoría: El rastro operativo

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

La colección incluye los siguientes campos clave:

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

• entity_id: Hace referencia al mandato correspondiente.

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

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

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

Registros de idempotencia: Manejo seguro de reintentos

La colección idempotency_records almacena claves de idempotencia para evitar operaciones duplicadas. Utilice esta colección para conservar la clave proporcionada por el cliente, el agente que realizó la solicitud y el asiento contable creado para dicha operación. Añada un índice TTL para eliminar automáticamente los registros después de 24 horas.

La colección incluye los siguientes campos clave:

• idempotency_keyAlmacena 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 elimina 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