O Mercado Pago Commerce Agents Checkout é uma biblioteca open source em Python, disponível em beta, que implementa um checkout_handoff seguro na sua integração. Com ela, você aciona o Checkout Pro diretamente no fluxo do agente, sem transferir para o modelo o controle de preços, credenciais ou da criação do pagamento.

Se você já explora agentes de compra com a stack open source commerce-agents, da Anthropic, a biblioteca incorpora o checkout do Mercado Pago ao fluxo existente. Ela também pode ser integrada a outros backends de agentes desenvolvidos em Python por meio de adaptadores para o carrinho, o catálogo e a persistência de tentativas de checkout.

A biblioteca usa o SDK oficial do Mercado Pago e a API de Orders para preparar o checkout no backend da sua integração. Antes de criar uma order, ela consulta o catálogo confiável da aplicação e valida os dados necessários para o pagamento.

1. Valida o carrinho no seu catálogo: antes de criar uma order, confere itens, preços e moeda com as informações confiáveis da sua aplicação.
2. Cria uma order para o Checkout Pro: depois da validação, prepara o pagamento no checkout hospedado do Mercado Pago.
3. Devolve uma URL de pagamento validada: envia ao host a URL do Checkout Pro somente após validá-la nos domínios do Mercado Pago.
4. Mantém credenciais e valores no backend: Access Token, preços e URL de pagamento não passam pelo contexto do modelo.

Acionar o checkout_handoff não confirma o pagamento. Você continua responsável por persistir idempotency_key e external_reference, tratar estados indeterminados, processar webhooks e reconciliar as Orders antes de liberar a compra.

A versão beta 0.1.0 está disponível no PyPI e requer Python 3.11 ou superior, além do SDK mercadopago 3.5.0 ou superior.

Se preferir realizar a integração manualmente, instale o pacote:

bash
Copiar
pip install mercadopago-commerce-agents-checkout==0.1.0

Consulte o repositório oficial do Commerce Agents Checkout para conhecer os requisitos, revisar exemplos de implementação e enviar feedback.

O plugin mercadopago-commerce analisa seu projeto e orienta você a incorporar o Commerce Agents Checkout no ponto adequado. Ele não depende de um framework, de uma estrutura de repositório ou de um segmento comercial específico.

A análise começa em modo somente leitura e apresenta um plano antes de modificar o projeto.

1. Descobre os limites reais da integração: identifica o carrinho, o catálogo confiável, o ponto de início do checkout e o canal usado para entregar a URL fora do contexto do modelo.
2. Detecta como o projeto gerencia dependências: reconhece configurações baseadas em uv, Poetry, Pipenv, pyproject.toml ou requirements.txt.
3. Usa uma versão validada da biblioteca: adiciona a versão exata compatível e gera um adaptador pequeno sobre a arquitetura existente.
4. Detecta requisitos pendentes: se não encontrar persistência durável, webhooks, reconciliação ou um limite seguro para entregar a URL, informa esses pontos como bloqueios em vez de inventar uma implementação.

A integração automática está disponível para backends de agentes desenvolvidos em Python 3.11 ou superior. Se o projeto usar outra tecnologia, o plugin não altera o código: apresenta o contrato oficial da API de Orders e as considerações de segurança necessárias para uma integração manual.

Para instalar o plugin público com o Claude Code:

bash
Copiar
claude plugin marketplace add \
  https://github.com/mercadopago/mercadopago-claude-marketplace.git \
  --scope project

claude plugin install \
  mercadopago-commerce@mercadopago-claude-marketplace \
  --scope project

Na raiz do projeto que você quer analisar, execute:

text
Copiar
/mercadopago-commerce:mp-commerce analyze

O plugin exibirá o diagnóstico e o plano de integração. Ele não fará alterações até que você confirme explicitamente o plano proposto.

Você também pode explorar o plugin mercadopago-commerce para Claude Code e o projeto open source commerce-agents, da Anthropic.