Introdução ao AP2

O AP2 (Agent Payments Protocol) é um protocolo projetado para transações de pagamento realizadas por agentes de software, suportando fluxos de trabalho tanto com a participação humana quanto autônomos. Este guia explora a implementação de referência do AP2 em Python e seus componentes fundamentais.

Estrutura do Projeto de Amostra

A base de código de exemplo está organizada da seguinte forma:

samples/python/
├── src/ap2/                    # Código central do protocolo AP2
├── scenarios/                  # Demonstrações de cenários de uso
│   └── a2a/human-present/     # Cenários com interação humana
│       ├── cards/             # Exemplos com cartões
│       └── x402/              # Exemplos com x402
├── pyproject.toml             # Configuração de dependências
└── README.md                  # Documentação do projeto

Pré-requisitos do Ambiente

• Python versão 3.10 ou superior.
• O gerenciador de pacotes uv.
• Uma chave de API do Google para funcionalidades de IA.

Procedimento de Instalação

1. Configurando o gerenciador de pacotes uv

Se ainda não estiver instalado, siga as instruções oficiais para instalar o uv.

2. Obtendo as dependências do projeto

Clone o repositório e instale os pacotes necessários:

# Obter o código fonte
git clone https://github.com/google-agentic-commerce/AP2.git

# Acessar o diretório do projeto
cd AP2/samples/python

# Resolver e instalar as dependências
uv sync

3. Definindo a Chave de API do Google

Adquira uma chave no AI Studio do Google. Uma das formas de configurá-la é através de uma variável de ambiente:

export GOOGLE_API_KEY=CHAVE_DA_SUA_API_AQUI

Componentes Essenciais do Protocolo

Entidades Principais (Key Actors)

• Agente de Compras (Shopping Agent): Orquestrador central que processa as solicitações do usuário e delega tarefas a agentes especializados.
• Agente do Comerciante (Merchant Agent): Responsável por responder a consultas de produtos originadas pelo Agente de Compras.
• Agente Processador de Pagamentos do Comerciante: Lida com a execução das transações financeiras em nome do comerciante.
• Agente Provedor de Credenciais: Atua como um carteira digital, gerenciando os métodos de pagamento e endereços de entrega do usuário.

Estruturas de Dados Fundamentais

• IntentMandate: Define a intenção inicial de compra.
• CartMandate: Representa o carrinho de compras e é assinado pelo comerciante para garantir a precisão da cotação.
• PaymentMandate: Contém os detalhes da transação e requer a assinatura do usuário para autorização.

Cenários de Implementação

Cenário 1: Pagamento com Cartão e Interação Humana

Este é o fluxo mais comum, onde o usuário confirma ativamente os detalhes da compra e o método de pagamento.

Inicialização dos Serviços

Execute cada agente em um terminal separado:

# No diretório AP2/samples/python

# 1. Iniciar o Agente do Comerciante
uv run --package ap2-samples python -m roles.merchant_agent

# 2. Iniciar o Agente Provedor de Credenciais
uv run --package ap2-samples python -m roles.credentials_provider_agent

# 3. Iniciar o Agente Processador de Pagamentos
uv run --package ap2-samples python -m roles.merchant_payment_processor_agent

# 4. Iniciar a Interface do Agente de Compras (para desenvolvimento)
uv run --package ap2-samples adk web src/roles

Fluxo de Passo a Passo

1. Acesse a interface de desenvolvimento em http://0.0.0.0:8000/dev-ui.
2. Selecione o shopping_agent no menu.
3. Digite uma intenção de compra (ex: "Quero comprar uma cafeteira").
4. O Agente de Compras solicita ao Agente do Comerciante que busque produtos.
5. O comerciante retorna um CartMandate com os itens e preços.
6. O usuário escolhe um produto da lista apresentada.
7. O sistema conecta ao Agente Provedor de Credenciais para listar os métodos de pagamento disponíveis.
8. O usuário seleciona um método de pagamento.
9. É criado um PaymentMandate que é enviado para assinatura do usuário.
10. Na demonstração, utilize o OTP simulado 123 para autorizar.
11. A compra é concluída e um recibo digital é gerado.

Cenário 2: Pagamento via x402

Suporta métodos de pagamento compatíveis com x402. A configuração é semelhante ao cenário com cartão, utilizando scripts e configurações específicas para x402.

Funcionalidades Avançadas

Moddo Detalhado (Verbose Mode)

Para diagnosticar e entender o fluxo interno, solicite o modo detalhado em sua mensagem:

"Quero comprar um sapato novo. Ative o modo detalhado, explique suas ações e mostre todas as cargas de dados."

Este modo expõe:

• Descrições passo a passo das operações.
• Representações JSON de todas as estruturas de dados trocadas.
• Os objetos de mandato (Intent, Cart, Payment) conforme são criados, enviados e recebidos.

Logs de Comunicação entre Agentes

Um arquivo de log detalhado, watch.log, é gerado automaticamente no diretório .logs. Ele categoriza as informações em:

Tipo de Log	Conteúdo
Dados HTTP Brutos	Método, URL, corpo da requisição e resposta em JSON.
Mensagens A2A	Instruções extraídas de TextPart e dados de DataPart das mensagens A2A.
Protocolo AP2	Objetos de mandato identificados dentro dos DataPart das mensagens.

Arquitetura do Código

Construtor de Mensagens A2A

A classe A2aMessageBuilder facilita a criação de mensagens estruturadas:

construtor = A2aMessageBuilder()
mensagem = construtor.add_text("Olá").add_data("chave", dados).build()

Executor Base para Servidores de Agente

BaseServerExecutor fornece a infraestrutura para implementar um agente, lidando com:

• Processamento de requisições e respostas.
• Gerenciamento de extensões do protocolo.
• Resolução e execução de ferramentas.

Validação do Pagamento

A integridade das transações é assegurada por rotinas de validação de assinatura:

def verificar_assinatura_mandato_pagamento(mandato: PaymentMandate) -> None:
    if mandato.autorizacao_usuario is None:
        raise ValueError("Autorização do usuário não encontrada no PaymentMandate.")

Detalhes do Agente Provedor de Credenciais

Este agente é central para a segurança e gerenciamento de dados de pagamento. Seu código reside em samples/python/src/roles/credentials_provider_agent/.

Ponto de Entrada (__main__.py):

• Carrega a descrição do agente a partir de agent.json.
• Inicia o servidor na porta 8002, exposto no caminho RPC /a2a/credentials_provider.
• Instancia o CredentialsProviderExecutor.

Lógica Principal (agent_executor.py):

• CredentialsProviderExecutor herda de BaseServerExecutor e opera com um system prompt focado em operações via ferramentas.
• Ferramentas Registradas:
  • handle_obter_endereco_entrega
  • handle_pesquisar_metodos_pagamento
  • handle_criar_token_credencial_pagamento
  • handle_assinar_mandato_pagamento
  • handle_obter_credenciais_brutas_metodo_pagamento

Gerenciamento de Contas e Tokens (account_manager.py):

• Simula um banco de dados em memória com contas de usuário, contendo endereço de entrega e uma variedade de métodos de pagamento.
• Gerencia o ciclo de vida dos tokens:
  • criar_token(email, apelido): Gera um token único associado a um método de pagamento.
  • atualizar_token(token, mandato_pagamento_id): Vincula o ID do mandato assinado ao token.
  • verificar_token(token, mandato_pagamento_id): Valida a associação e retorna as credenciais brutas (ex: número do cartão criptografado).

Fluxo de Interação Típico:

1. O Agente de Compras consulta os métodos de pagamento disponíveis que atendem aos critérios do comerciante.
2. Após a seleção do usuário, é gerado um token de credencial para o método escolhido.
3. O PaymentMandate é assinado pelo usuário e o ID do mandato é vinculado permanentemente ao token.
4. Durante a liquidação final, o Agente Processador de Pagamentos utiliza o par (token, mandato_pagamento_id) para obter as credenciais necessárias para processar o pagamento.

Desenvolvendo Extensões

Implementando um Novo Método de Pagamento

Para adicionar suporte a uma nova forma de pagamento:

1. Declare a extensão no manifesto agent.json do agente relevante.
2. Implemente a lógica de negócio necessária nas ferramentas do agente.
3. Atualize as regras de validação conforme o novo método.

Criando um Novo Papel de Agente

Para desenvolver um agente com uma função totalmente nova:

1. Crie uma classe que herde de BaseServerExecutor.
2. Implemente as ferramentas (métodos decorados) que definirão as capacidades do agente.
3. Escreva o arquivo de descrição agent.json para publicar suas habilidades.

Resolução de Problemas Comuns

Falhas na Configuração

• Erro de Chave de API do Google: Verifique se a variável de ambiente está definida corretamente e se a chave é válida.
• Conflito de Portas: Certifique-se de que as portas 8000 a 8003 não estão em uso por outros processos. Os valores podem ser alterados nos arquivos de configuração.
• Falha ao Instalar Dependências: Confirme a versão do Python (>=3.10). Limpe o cache do uv com uv cache clean e tente novamente.

Estratégias de Depuração

1. Analise o arquivo watch.log para entender o fluxo completo de comunicação entre os agentes.
2. Utilize o modo detalhado para obter insights passo a passo das operações do agente.
3. Monitore as saídas no console de cada serviço em execução.

Diretrizes de Implementação

• Segurança: Valide sempre a assinatura digital de qualquer mandato recebido antes de processá-lo.
• Tratamento de Erros: Implemente capturas de exceções robustas e retorne mensagens de erro claras.
• Auditoria: Mantenha logs detalhados de todas as transações e ações críticas para fins de depuração e auditoria.
• Testes: Desenvolva testes abrangentes que cubram todos os fluxos de pagamento antes de implantar em ambiente de produção.