← Voltar à lista

Agentes A2A que chamam a API de um site

Os agentes A2A permitem que um sistema de IA encontre outro, delegue uma tarefa e receba um resultado estruturado. Quando esse agente consegue chamar a API de um site, ele passa a participar de um processo real de negócio: verifica estoque, cria solicitações, calcula orçamentos, atualiza pedidos ou coleta dados para relatórios.

  • A2A - um protocolo de comunicação entre agentes
  • API do site - um ponto de acesso controlado a dados e operações
  • Agent Card - a descrição das capacidades e dados de conexão
  • Task - uma tarefa com status, resultado e histórico
  • Princípio central - o agente chama operações aprovadas, não URLs arbitrárias

O que é A2A

A2A, ou Agent2Agent, conecta agentes independentes. Um atua como cliente, enquanto o outro publica suas capacidades e executa tarefas. Eles podem usar linguagens, modelos e infraestruturas diferentes.

O fluxo típico é:

  1. O agente cliente recebe a solicitação do usuário.
  2. Ele encontra um agente remoto pela Agent Card.
  3. Cria uma tarefa e envia o contexto.
  4. O agente remoto chama a API do site.
  5. O resultado retorna como mensagem ou artefato.

O A2A cuida da comunicação entre agentes, enquanto a API oferece acesso às funções do site. Essas camadas se complementam, mas não se substituem.

Por que um agente precisa da API do site

Sem uma API, o agente normalmente fica limitado a texto, busca em documentos ou automação frágil da interface. A API fornece um contrato previsível e permite agir sem imitar cliques.

Operações úteis:

  • pesquisar produtos, serviços e conteúdos;
  • calcular preço, prazo ou plano;
  • criar lead, solicitação ou pedido;
  • consultar pagamento e entrega;
  • atualizar perfil ou reserva;
  • obter um resultado personalizado após autorização.

Por exemplo, um agente consultor pode pedir ao agente do site: "Encontre um plano disponível para uma equipe de 20 pessoas". O agente verifica as regras atuais pela API interna e devolve opções estruturadas.

Arquitetura da integração

Uma solução prática tem cinco partes:

Componente Responsabilidade
Agente cliente Entende a intenção e escolhe o provedor
Servidor A2A Recebe tarefas, mensagens e consultas de status
Camada de ferramentas Converte a intenção em uma chamada específica
API do site Verifica permissões, valida dados e executa a operação
Auditoria Mantém um histórico seguro das chamadas

Não entregue ao modelo uma ferramenta universal como request(url, method, body). Defina funções restritas:

search_products(query, filters)
calculate_quote(product_id, quantity)
create_lead(name, contact, consent)
get_order_status(order_id)

Isso facilita o controle de permissões, a validação, os testes e a auditoria.

Agent Card e descrição das capacidades

A Agent Card ajuda o cliente a entender quais tarefas o agente pode executar. Geralmente inclui nome, descrição, URL, métodos de autenticação e uma lista de skills.

A descrição de uma skill deve ser específica. "Trabalha com o site" diz pouco. É melhor: "Pesquisa o catálogo, calcula orçamentos e cria uma solicitação após a confirmação do usuário".

Não publique na Agent Card:

  • chaves de API ou tokens internos;
  • endereços privados de serviços;
  • detalhes que facilitem contornar a autorização;
  • operações indisponíveis para clientes externos.

Autenticação e permissões

A conexão A2A e a chamada à API podem usar credenciais diferentes. O agente comprova sua identidade e a API determina em nome de quem a ação é realizada.

Três modos comuns:

  1. Conta de serviço - para dados compartilhados e operações em segundo plano.
  2. Acesso delegado do usuário - para pedidos, perfis e dados pessoais.
  3. Operação confirmada - o agente prepara a ação e o usuário aprova antes da escrita.

Limite permissões por endpoint, método HTTP, usuário e tipo de dado. Ler o catálogo não deve permitir alterar preços ou excluir pedidos.

Segurança das chamadas

Os principais riscos são injeção de instruções, argumentos incorretos, vazamento de dados e execução duplicada.

Proteções mínimas:

  • validar entradas com um schema rígido;
  • limitar operações por allowlist;
  • manter segredos fora de prompts e mensagens A2A;
  • usar idempotency key em criação e pagamento;
  • limitar frequência e custo das chamadas;
  • confirmar ações financeiras e irreversíveis;
  • mascarar dados pessoais e tokens nos logs;
  • retornar apenas os campos necessários ao agente.

Textos de usuários e outros agentes são entradas não confiáveis. Mesmo uma instrução convincente em um documento nunca deve ampliar as permissões da ferramenta.

Tarefas síncronas e demoradas

Busca e cálculo podem responder imediatamente. Importação, relatórios grandes ou processamento de pedidos podem levar minutos. Nesses casos, são úteis os status submitted, working, completed, failed e canceled.

O cliente pode receber atualizações por streaming de eventos, webhook ou consulta de status. Uma reconexão não pode reiniciar a operação de negócio.

Erros e observabilidade

O agente precisa de um resultado claro, não de um stack trace: indisponibilidade temporária, argumento inválido, acesso negado ou confirmação necessária. Detalhes internos ficam em logs protegidos.

Para diagnóstico, registre:

  • identificadores de task, sessão e usuário;
  • nome da ferramenta chamada;
  • cópia segura dos argumentos;
  • código da API e duração;
  • status da confirmação;
  • versões do agente e do schema.

Assim é possível separar erros do modelo de falhas de API, rede ou regra de negócio.

Plano de implementação

  1. Escolha um caso com valor mensurável.
  2. Defina um contrato de API restrito e schemas de dados.
  3. Crie ferramentas separadas em vez de acesso HTTP universal.
  4. Adicione autenticação, limites e auditoria.
  5. Publique uma Agent Card com skills precisas.
  6. Teste erros, repetições, cancelamento e entradas maliciosas.
  7. Comece em modo read-only ou rascunho.
  8. Permita escrita somente após analisar logs reais.

Resumo

Um agente A2A com acesso à API do site pode conectar sistemas externos de IA a serviços reais do negócio. Uma integração confiável depende de ferramentas restritas, schemas rígidos, permissões limitadas, confirmações e auditoria, não de liberdade ilimitada para o modelo.

Quer conectar um agente A2A à API do seu site - entre em contato.

Perguntas frequentes

Qual é a diferença entre A2A e uma API REST comum?

Uma API REST descreve operações de uma aplicação, enquanto o A2A cobre a comunicação entre agentes e o ciclo de vida das tarefas. O A2A pode usar REST ou outro transporte, e depois o agente acessa a API do site por ferramentas controladas.

Preciso de A2A se meu agente já chama uma API?

Nem sempre. Uma chamada direta pode bastar para um único agente interno. O A2A é útil quando agentes independentes precisam se encontrar, delegar tarefas e trocar resultados por um protocolo comum.

Posso dar ao agente um cliente HTTP universal?

Tecnicamente sim, mas isso é arriscado em produção. Funções restritas com allowlist, schemas e permissões separadas são mais fáceis de proteger, testar e auditar.

Como evitar a criação duplicada de um pedido?

Use uma idempotency key e salve a relação entre a task A2A e a operação de negócio. Uma solicitação repetida com a mesma chave deve retornar o resultado anterior, não criar outro registro.

Quais ações exigem confirmação?

Confirme pagamentos, publicações, mensagens externas, alterações de dados pessoais e outras ações caras ou irreversíveis. Busca, leitura de dados públicos e preparação de rascunhos normalmente podem ser automatizadas.

Contato