Descoberta pública de agentes
Use estes exemplos para moldar o JSON que outro cliente A2A busca antes de decidir se seu agente pode concluir uma tarefa.
6 modelos JSON prontos para copiar · A2A v1.0
Exemplos de A2A Agent Card
Navegue por modelos práticos A2A v1.0, entenda suas decisões de design, e depois adapte qualquer exemplo para o seu próprio agente.
Envio para marketplace
Adapte provedor, skills, tags, capabilities, e metadados de segurança para que os revisores entendam o que o agente faz e quem o opera.
Catálogos internos de agentes
Padronize descrições de endpoint, autenticação, e skills entre agentes internos antes que as equipes os integrem em fluxos de trabalho.
Modelos JSON
Agent Cards de exemplo para agentes de suporte, reservas, compras, programação, pesquisa, e fluxo de trabalho.
Filtro
Agente de Suporte ao Cliente
Lida com perguntas sobre produtos, consultas de pedidos, devoluções, e transferências de escalonamento.
Por que é construído assim
- Credenciais de cliente OAuth 2.0 protegem dados de pedidos: o Agent Card declara a URL do token e o escopo para que os clientes possam se autenticar sem documentação fora de banda.
- streaming e pushNotifications são ambos true porque as conversas de suporte são de longa duração e as atualizações de resolução chegam de forma assíncrona.
- A única skill é limitada a um único limite de tarefa (classificar, resolver, escalar) em vez de uma descrição vaga de "ajudar clientes", para que os roteadores possam corresponder com precisão.
{
"name": "Agente de Suporte ao Cliente",
"description": "Responde a perguntas de suporte ao cliente, recupera o contexto do pedido e encaminha problemas não resolvidos para uma equipe humana.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Exemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "resolve-customer-support-request",
"name": "Resolver solicitação de suporte ao cliente",
"description": "Classifica uma solicitação de suporte ao cliente, reúne o contexto necessário, propõe uma resolução e escala quando a confiança está baixa.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Ajude-me a devolver meu pedido."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Agente de Reservas
Encontra horários de compromisso disponíveis e prepara confirmações de reserva.
Por que é construído assim
- Uma chave de API em um cabeçalho é suficiente aqui: as reservas têm escopo de locatário, mas não carregam o problema de consentimento de usuário delegado que o OAuth resolve.
- defaultOutputModes é apenas application/json, sinalizando que os chamadores obtêm propostas de reserva estruturadas em vez de prosa.
- pushNotifications é true para que o agente possa confirmar uma reserva depois que o backend que mantém o horário se estabilizar, sem que o cliente precise fazer polling.
{
"name": "Agente de Reservas",
"description": "Pesquisa disponibilidade, propõe opções de reserva e prepara reservas para aprovação.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/booking",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Exemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "find-and-prepare-booking",
"name": "Encontre e prepare a reserva",
"description": "Verifica a disponibilidade de recursos, compara janelas de reserva e retorna uma proposta de reserva estruturada.",
"tags": [
"booking",
"calendar",
"availability"
],
"examples": [
"Encontre um compromisso de 30 minutos amanhã à tarde."
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}Agente de Compras
Compara produtos, disponibilidade, preços, e restrições de compra.
Por que é construído assim
- As recomendações classificadas chegam em streaming à medida que são calculadas, então streaming é true enquanto pushNotifications permanece false — nada acontece depois que a resposta é concluída.
- A descrição da skill se compromete a retornar trade-offs e justificativas, o que informa aos orquestradores que este agente explica classificações em vez de apenas listar produtos.
- Os escopos OAuth controlam dados relacionados à compra; uma demonstração pública de compras poderia eliminar completamente a segurança e ainda ser um Agent Card válido.
{
"name": "Agente de Compras",
"description": "Compara produtos com as restrições do usuário e retorna opções de compra classificadas com compensações.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/shopping",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Exemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "compare-shopping-options",
"name": "Compare opções de compras",
"description": "Avalia produtos candidatos, filtra por restrições e retorna recomendações classificadas com justificativa.",
"tags": [
"shopping",
"commerce",
"recommendations"
],
"examples": [
"Compare laptops leves abaixo de US$ 1.200."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/shopping/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Agente de Programação
Revisa tarefas de código, propõe patches, e explica decisões de implementação.
Por que é construído assim
- extendedAgentCard é true: o Agent Card público lista uma skill genérica de "implementar mudança de código", enquanto skills específicas de repositório só são reveladas a clientes autenticados via GetExtendedAgentCard.
- Tanto saídas text/plain quanto application/json são declaradas porque o agente retorna explicações legíveis por humanos junto com patches aplicáveis por máquina.
- O streaming importa para longos ciclos de compilação e teste; os clientes veem progresso intermediário em vez de uma chamada silenciosa de vários minutos.
{
"name": "Agente de Programação",
"description": "Auxilia nas tarefas de engenharia de software analisando código, propondo alterações e retornando notas de implementação.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/coding",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Exemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "implement-code-change",
"name": "Implementar mudança de código",
"description": "Lê uma solicitação de codificação, inspeciona arquivos relevantes, retorna uma proposta de patch e resume as etapas de verificação.",
"tags": [
"coding",
"review",
"patches"
],
"examples": [
"Adicione paginação à API de usuários."
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}Agente de Pesquisa
Coleta fontes, extrai evidências, e retorna notas de pesquisa estruturadas.
Por que é construído assim
- Nenhum securitySchemes: o endpoint é intencionalmente público, e omitir o campo é a forma correta de dizer isso — um mapa de esquemas vazio seria ambíguo.
- A entrada é apenas text/plain, porque os briefings de pesquisa começam a partir de perguntas em linguagem natural; a saída estruturada chega como notas application/json.
- Este é o Agent Card v1.0 mínimo útil: identidade, uma interface, capabilities, modos, e uma skill bem marcada.
{
"name": "Agente de Pesquisa",
"description": "Coleta material de origem, extrai evidências e produz notas de pesquisa estruturadas com citações.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/research",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Exemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "prepare-research-brief",
"name": "Preparar resumo de pesquisa",
"description": "Pesquisa fontes aprovadas, extrai afirmações e evidências e retorna um resumo conciso da pesquisa.",
"tags": [
"research",
"evidence",
"citations"
],
"examples": [
"Prepare um resumo citado sobre a política de energia renovável."
]
}
]
}Agente de Fluxo de Trabalho Interno
Coordena aprovações, verificações de status, e atualizações de fluxo de trabalho de back-office.
Por que é construído assim
- application/json é o único modo de entrada e saída: este agente é chamado por outros sistemas, nunca por pessoas digitando prosa.
- OAuth 2.0 mais extendedAgentCard se encaixa em auditorias corporativas — as equipes de segurança podem ver os requisitos de autenticação publicamente enquanto skills sensíveis de fluxo de trabalho permanecem atrás da autenticação.
- pushNotifications é essencial porque as cadeias de aprovação levam horas ou dias; webhooks substituem o polling para mudanças de estado.
{
"name": "Agente de Fluxo de Trabalho Interno",
"description": "Coordena aprovações internas, verifica o status do sistema e prepara atualizações de fluxo de trabalho para equipes de operações.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/workflow",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Exemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "coordinate-internal-workflow",
"name": "Coordenar o fluxo de trabalho interno",
"description": "Recebe a intenção do fluxo de trabalho, verifica os requisitos da política, reúne aprovações e relata o status final.",
"tags": [
"workflow",
"operations",
"approval"
],
"examples": [
"Solicite aprovação para implantar a atualização da folha de pagamento."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/workflow/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Adapte com confiança
Como adaptar um exemplo de Agent Card
Cada exemplo de Agent Card é intencionalmente completo o suficiente para copiar, mas o Agent Card não deve ser publicado sem alterações. Trate-o como um mapa de campos para seu próprio servidor A2A: substitua identidade, endpoint, provedor, autenticação, capabilities, modos, e detalhes de skills por valores de produção.
Os Agent Cards mais fortes explicam o limite da tarefa do agente tanto em linguagem simples quanto em metadados legíveis por máquina. Um cliente deve conseguir saber o que o agente pode fazer, o que não pode fazer, qual URL chamar, e se credenciais são necessárias.
Antes de publicar
Substitua cada URL example.com pelo seu endpoint A2A implantado e site do provedor.
Reescreva o nome da skill, descrição, tags (obrigatórias na v1.0), e exemplos para o limite de tarefa real.
Defina provider.organization e incremente a version de nível superior sempre que o conteúdo do Agent Card mudar.
Remova campos de autenticação apenas quando o endpoint for intencionalmente público.
Mantenha defaultInputModes e defaultOutputModes alinhados com o que seu servidor realmente aceita e retorna.
Valide o JSON final e publique-o em /.well-known/agent-card.json no domínio do seu serviço.
Pronto para construir
Comece com um exemplo e depois faça dele o seu.
Abra qualquer padrão no Gerador de Agent Card, revise o JSON, e valide-o antes de publicar.