Mandate Ledger para comércio agente confiável no MongoDB

Estabeleça a confiança com AP2

O Protocolo de Pagamentos de Agentes (AP2) do Google fornece um protocolo aberto, seguro e interoperável que cria um ecossistema confiável para comerciantes, instituições financeiras e clientes comuns.

Figura 1. A camada de confiança

O AP2 protege as transações por meio de Credenciais Digitais Verificáveis (VDCs) — cargas úteis JSON insensíveis e assinadas criptograficamente que os agentes criam e trocam. O API2 categoriza esses VDCs em três mandatos principais:

• O Mandato de Intenção: descreve o que o cliente exige e define as condições sob as quais um agente de IA pode fazer uma compra em nome do cliente.

• O Mandato do Carrinho: Fornece um recibo digital assinado pelo comerciante e pelo cliente para autorizar compras com presença humana.

• O Mandato de Pagamento: cria uma camada de visibilidade compartilhada diretamente com a rede de pagamento para sinalizar com segurança o envolvimento do agente de IA.

Os VDCs atuam como contratos digitais permanentes. Os agentes assinam criptograficamente essas cargas para capturar a intenção do cliente. Esse processo cria um rastro de auditoria não repudiável para cada etapa da experiência de compra.

Figura 2. Uma conversa contratual com prova verificável em cada etapa

Figura 3. Visualização de intenção na interface do usuário, mostrando como cada intenção é representada na conversa

Garanta a responsabilidade com o MongoDB Atlas

Para que esses VDCs criptográficos permaneçam confiáveis, os sistemas devem armazená-los em um ambiente seguro e verificável. O Mandate Ledger Service atua como o middleware de proteção entre os agentes de IA e o banco de dados. Por trás desse middleware está o MongoDB Atlas.

O Atlas oferece segurança de nível empresarial projetada para oferecer suporte a um registro de auditar à prova de adulterções. Crie essa arquitetura para criar a camada de confiança imutável, o Mandate Ledger Service, necessário para dimensionar o comércio agente seguro.

Imagine um cliente pedindo a um assistente de IA para comprar um novo smartphone. O agente de compras negocia autonomamente com os comerciantes para encontrar o negócio perfeito. O serviço de registro de mandatos registra toda essa jornada empacotando cada solicitação, aprovação e etapa de checkout em mandatos JSON criptograficamente assinados. O MongoDB Atlas armazena cada mandato como um documento imutável. Esse processo transforma um bate-papo simples em uma prova de intenção permanente e não repudiável.

Esta solução mostra como criar o serviço Mandate Ledger em uma arquitetura que usa o protocolo AP2.

O Ledger Service: um escudo protetor

O serviço Mandate Ledger atua como um middleware de proteção que conecta o agente comercial ao banco de dados. Crie este serviço usando FastAPI ou gRPC.

Figura 5. Arquitetura detalhada do serviço de registro

Processe todas as solicitações de agente por três camadas distintas e seguras:

• A camada de autenticação: valida as chaves de API para identificar agentes com segurança. Ele aplica o controle de acesso baseado em função (RBAC) por tipo de agente para forçar permissões rígidas do agente.

• A Camada de Lógica de Negócios: executa a validação de solicitações principais e o controle de concorrência. Ele impõe a idempotência para novas tentativas de rede seguras e oferece suporte à imutabilidade estrita do mandato.

• A camada de acesso aos dados: usa o cliente MongoDB e a indexação otimizada para executar operações de banco de dados. Essa camada define o campo _id como imutável e bloqueia todas as operações de atualizar e excluir por meio da validação de esquema.

A cadeia de mandatos: da intenção ao pagamento

Cada transação AP2 progride por meio de uma sequência estruturada de mandatos criptograficamente assinados. Cada etapa produz um registro imutável no MongoDB Atlas, criando um rastro de auditoria completo da intenção ao pagamento.

Figura 6. Fluxo de dados

Para mover uma transação da intenção para o pagamento, os agentes AP2 concluem a seguinte sequência de transações:

1. Capture a intenção do cliente. O agente de compras traduz a solicitação do cliente, como uma descrição em linguagem natural de "tênis de corrida", em um mandato de intenção estruturado. O mandato de intenção captura o comerciante de destino, os requisitos de reembolso, as preferências de confirmação do carrinho e uma janela de expiração. O agente de compras assina o mandato usando EdDSA em nome do cliente e o envia ao agente do comerciante com um status de signed e um hash de versão bloqueando seu conteúdo.

2. Armazenar o Mandato de Intenção. O Agente Comerciante grava o Mandato de Intenção no Atlas por meio do Serviço de Razão de Mandatos. O serviço de razão valida a solicitação, aplica o RBAC e anexa o registro de forma imutável.

3. Crie o Mandato do Carrinho. O Agente Comerciante cria uma oferta de carrinho contendo todos os detalhes do produto: nome do item, preço, moeda, métodos de pagamento aceitos e validade. O Agente Comerciante então o armazena no Atlas através do Serviço de Registro de Mandatos, onde o registro recebe um status de proposed e um hash de versão para garantir a integridade.

4. Ofereça o carrinho ao cliente. O agente do comerciante retorna o mandato de carrinho proposto ao agente de compras, que apresenta as opções de produto disponíveis ao cliente.

5. Aceite o Mandato do Carrinho. O cliente seleciona uma opção. O agente de compras coassina o Mandato do Carrinho em nome do cliente usando uma chave de dispositivo com suporte de hardware e envia o mandato aceito de volta ao agente do comerciante.

6. Contrassinar e finalizar o Mandate do carrinho. O agente do comerciante adiciona sua assinatura criptográfica ao carrinho aceito e armazena o Mandate do carrinho totalmente assinado duplamente no Atlas, bloqueando os termos acordados com um status signed.

7. Crie o mandato de pagamento. O agente de compras consulta o provedor de credenciais para recuperar o token de pagamento apropriado. O agente de compras então cria e assina o mandato de pagamento em nome do cliente e o envia ao agente comercial. O provedor de credenciais nunca retorna números completos de cartão de crédito, o que garante que o agente de compras nunca acesse dados brutos.

8. Armazene o mandato de pagamento. O agente comercial grava o mandato de pagamento assinado no Atlas por meio do serviço de registro de mandatos. O serviço de registro compartilha esse mandato diretamente com instituições financeiras para sinalizar o envolvimento do agente de IA, e o processador de pagamento usa esse mandato para rotear a autorização para a rede de pagamento.

Os agentes não podem modificar ou excluir registros existentes. O MongoDB Atlas impõe gravações somente de acréscimo, de modo que toda a cadeia de mandatos — intenção, carrinho e pagamento — permanece intacta e verificável de forma independente pelo agente auditor a qualquer momento.

O Mandate Ledger: um armazenamento de documentos polimórfico

A coleção mandate_ledger armazena todos os três tipos de mandato em uma única coleção. Use o campo entity_type para distingui-los no momento da query, o que elimina a necessidade de joins ou coleções separadas por tipo de mandato.

Todos os documentos compartilham uma estrutura de envelope comum:

{
  "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": { ... }
}

O campo mandate_data carrega a carga útil específica do tipo, onde cada tipo de mandato armazena uma estrutura de dados 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..."
}

Pagamentos: O registro de conclusão ultra-enxuto

A coleção payments armazena um documento por transação concluída. Esta coleção aplica o padrão de Referência estendida.

Em vez de fazer embedding do conteúdo completo do mandato, cada documento armazena apenas o ID do mandato e a assinatura de autorização para cada um dos três mandatos. Esse design mantém o registro de pagamento pequeno e rápido de ler, preservando um ponteiro direto para os dados completos na coleção mandate_ledger quando um rastreamento completo para auditar é necessário.

{
  "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"
}

Esse design mantém intencionalmente o documento pequeno. Os termos completos, itens de linha e provas criptográficas residem na coleção mandate_ledger. O registro de pagamento existe apenas para confirmar que a transação está concluída e para fornecer os três ponteiros necessários para reconstruir a cadeia de auditar completa. Use o campo transaction_id para unir as duas coleções quando for necessário um rastreamento completo.

Chaves de API: identificação segura do agente

A coleção api_keys gerencia chaves de API para identificar agentes com segurança. Use esta coleção para armazenar as chaves associadas a cada agente que chamar o serviço.

Log de auditoria: o rastro operacional

A coleção audit_log armazena todas as operações da API para compliance e depuração. Use esta coleção para registrar eventos de nível de serviço, como criação de mandatos, tentativas de acesso e resultados de validação. Essa abordagem impede a expansão do próprio livro-razão de mandatos imutáveis. Adicione um índice TTL para remover automaticamente os registros após 90 dias. Isso preserva um rastro operacional útil enquanto mantém a coleção limitada.

A coleção inclui os seguintes campos-chave:

• event_type: Identifica o tipo de operação, como mandate.created.

• entity_id: Faz referência ao mandato relacionado.

• actor_agent_id: Captura qual agente realizou a ação.

• event_timestamp: registra quando o evento ocorreu e oferece suporte à política TTL.

• expires_at: Define quando o MongoDB exclui automaticamente o registro.

Registros de idempotência: tratamento de nova tentativa segura

A coleção idempotency_records armazena chaves de idempotência para evitar operações duplicadas. Use esta coleção para reter a chave fornecida pelo cliente, o agente que fez a solicitação e a entrada do livro-razão criada para essa operação. Adicione um índice TTL para remover automaticamente os registros após 24 horas.

A coleção inclui os seguintes campos-chave:

• idempotency_key: Armazena a chave exclusiva fornecida pelo cliente e requer um índice.

• agent_id: Identifica o agente que fez a solicitação.

• ledger_entry_id: Faz referência ao mandato criado para a solicitação original.

• expires_at: Define quando o MongoDB exclui automaticamente o registro.

Pré-requisitos

Antes de começar, verifique se você instalou e configurou o seguinte:

• MongoDB Atlas ou MongoDB autogerenciado 7.0 ou posterior

• Python 3.13 (versão 3.13.x)

• uv para gerenciamento de dependência

• Uma chave de API do Google ou acesso ao Vertex AI

• Docker para executar serviços como contêineres

• Node.js e npm para o aplicativo frontend

Procedimento