Gerador de Agent Card para JSON A2A

O que um gerador de Agent Card cria para o seu agente de IA

Um Agent Card é a descrição da interface pública de um agente A2A. Antes que outro agente possa decidir se deve chamar o seu serviço, ele precisa de mais do que uma URL: precisa de um relato confiável do propósito do agente, seu contrato técnico, suas skills e seus requisitos de acesso.

Este gerador de Agent Card transforma esses detalhes de implementação em JSON legível no formato A2A v1.0, mantendo a tomada de decisão próxima do formulário. Use-o depois de ter construído a lógica principal do agente e antes de implantá-lo ou listá-lo — o ponto onde um arquivo JSON escrito à mão geralmente quebra.

Torne seu agente descobrível

Um Agent Card claro dá aos clientes A2A um ponto de partida confiável: a quem o agente pertence, onde ele vive, e quais protocol bindings e versões ele fala.

Descreva uma interface utilizável

Capture a interface preferida, os modos de conteúdo, o comportamento de streaming e o suporte a notificações push de que outro agente precisa antes de fazer uma chamada.

Defina expectativas de acesso

Documente se o serviço é público, usa uma chave de API, ou requer OAuth 2.0, para que as integrações possam escolher o fluxo de autenticação correto — sem nunca colocar uma credencial no Agent Card.

Transforme skills em contratos claros

Nomeie o trabalho que seu agente pode executar, adicione as tags que a v1.0 exige mais exemplos úteis, e torne seus limites compreensíveis para pessoas, marketplaces e clientes de IA.

Como funciona o Gerador de Agent Card

Dos detalhes do serviço a um Agent Card publicável

O Gerador de Agent Card transforma detalhes do serviço em um documento JSON claro e publicável. Siga este fluxo de trabalho curto antes de enviar o Agent Card para produção.

1
Comece com o serviço real
Adicione o endpoint A2A público, o protocol binding, detalhes do provedor, a versão do agente, e os tipos de conteúdo que seu servidor aceita e retorna.
2
Defina limites de capacidade e skill
Selecione apenas as capacidades que sua implementação suporta, depois descreva uma skill representativa em linguagem clara e específica.
3
Revise o JSON gerado
Use a pré-visualização ao vivo para identificar campos ausentes, URLs de espaço reservado, ou descrições que não refletem com precisão o serviço implantado.
4
Valide e publique
Passe o Agent Card pelo validador, depois coloque o documento revisado em /.well-known/agent-card.json no domínio do seu serviço.

Quem usa o Gerador de Agent Card

Feito para todos que criam, publicam ou revisam Agent Cards

O Gerador de Agent Card ajuda criadores, equipes de plataforma e revisores a criar metadados de agente A2A consistentes sem começar de um arquivo JSON em branco.

Começar a partir de um exemplo em vez disso

Desenvolvedores de IA e independentes

Substitua um agent-card.json escrito à mão por um ponto de partida completo e no formato da especificação ao lançar um agente compatível com A2A.

Prompt engineers e product managers

Redija um documento de descoberta confiável a partir de uma descrição do serviço sem tocar na sintaxe JSON, depois entregue-o à engenharia para revisão.

Equipes de plataforma e DevOps

Padronize como os agentes internos descrevem endpoints, autenticação e skills antes de entrarem em um catálogo de agentes da empresa ou pipeline de CI.

Publicadores de marketplace

Prepare metadados de provedor, tags de skill e declarações de segurança que revisores e sistemas de classificação possam realmente analisar.

Perguntas frequentes

Perguntas sobre o gerador de Agent Card

Acerte o essencial antes que um cliente A2A encontre seu endpoint.

O que é um A2A Agent Card?

Um A2A Agent Card é um documento de descoberta JSON para um agente de IA. Ele comunica identidade, informações do provedor, interfaces suportadas, capacidades, skills, modos de conteúdo aceitos, e requisitos de segurança a clientes potenciais — o equivalente agente-a-agente de um README mais uma visão geral de API.

Por que usar um gerador de Agent Card em vez de escrever JSON à mão?

Agent Cards escritos à mão rotineiramente têm campos obrigatórios ausentes, nomes de campo anteriores à v1.0, ou erros de sintaxe. O gerador produz a forma atual A2A v1.0 — supportedInterfaces, provider.organization, tags de skill obrigatórias — e valida enquanto você digita, para que erros estruturais nunca cheguem à produção.

A qual versão A2A o Agent Card gerado se destina?

O gerador emite a estrutura A2A v1.0: um array ordenado supportedInterfaces com protocolBinding e protocolVersion por interface, uma version de agente de nível superior, e capabilities incluindo extendedAgentCard. Agent Cards com campos url ou preferredTransport de nível superior são anteriores à v1.0.

O JSON gerado precisa de revisão antes da produção?

Sim. O gerador cria um documento de partida prático, não um substituto para o seu contrato implantado. Confirme se endpoints, protocol bindings, skills e autenticação correspondem ao serviço que os usuários realmente acessarão.

Onde eu publico um Agent Card?

Publique o JSON revisado no mesmo domínio do seu serviço A2A em https://seu-dominio/.well-known/agent-card.json, o caminho well-known registrado pela especificação A2A. Muitas integrações mais antigas também verificam /.well-known/agent.json, então servir ambos é uma estratégia de transição segura.

Pronto para publicar

Volte ao Gerador de Agent Card antes de publicar.

Finalize os detalhes, revise o JSON gerado, e use a validação ao vivo antes de publicar seu Agent Card.

Abrir o Gerador de Agent Card Validar o JSON

Do blog

Guias práticos de descoberta A2A, escritos com base na especificação v1.0.

Todos os artigos

Ecosystem

Os artigos são publicados em inglês.