Como publicar o cartão A2A do seu produto, passo a passo

Um assistente de IA não sabe o que o seu produto faz só de ver a página de vendas. O cartão A2A é um arquivo curto que resolve isso. Ele fica num endereço padrão e diz o nome do agente, o que ele sabe fazer e como chamá-lo. Este tutorial cobre o cartão. Um agente que responde de verdade exige mais trabalho, e não está coberto aqui.

Passo 1: liste o que o agente faz

Escreva em uma lista curta as tarefas que o agente deve fazer. Por exemplo: "informar a carga horária do curso", "dizer o preço vigente" ou "explicar a garantia". Cada tarefa vira uma habilidade no cartão. Se a lista passar de cinco, corte. Um cartão com muita coisa confunde o assistente.

Passo 2: escreva o cartão

O cartão tem nome, descrição, endereço de chamada, habilidades e capacidades. Para um produto de conteúdo, deixe a transmissão em tempo real desligada, porque a resposta sai de uma vez:

"capabilities": {
  "streaming": false,
  "pushNotifications": false
}

Escreva a descrição com o que é público. Não coloque preço de promoção nem dado de aluno. O cartão é lido por qualquer um.

Passo 3: publique no endereço padrão

O cartão deve ficar em /.well-known/agent-card.json do seu domínio. Se você usa uma hospedagem comum, confira se o servidor deixa baixar arquivos desse caminho sem bloquear.

Passo 4: teste se o cartão responde

Abra o terminal e rode o comando abaixo. Troque o valor de D pelo domínio do seu site:

D=seudominio.com.br
curl -s -o /dev/null \
  -w "%{http_code}\n" \
  https://$D/.well-known/\
  agent-card.json

O resultado esperado é 200. Qualquer outro número quer dizer que o cartão não está no lugar certo. Depois, abra o endereço no navegador e confira se o JSON está válido.

Passo 5: confira o endereço de chamada

O campo de endereço do cartão precisa apontar para um lugar que responde. Um cartão que aponta para um endereço que não existe faz o assistente falhar sem explicar o motivo. Teste o endereço antes de publicar.

Passo 6: confira com a especificação

A especificação oficial do A2A define os campos obrigatórios. Compare o seu cartão com ela antes de divulgar. Os exemplos estão no site oficial.

O que você ainda não tem

Com o cartão no ar, o assistente vê o que você oferece, mas ainda não consegue pedir nada, a menos que o endereço de chamada responda. Essa é a próxima etapa, e exige um programa do seu lado.

Erros comuns

O erro mais comum é o caminho errado do arquivo. O segundo é o cartão com um campo de transmissão marcado como verdadeiro sem que o servidor transmita. O terceiro é um endereço de chamada com barra sobrando. Teste cada um com o comando do passo 4.

A especificação está em a2a-protocol.org, e o código do projeto, em GitHub.