Referência de schema · 14 fieldsA2A v1.0
Um Agent Card é o documento JSON padronizado que informa aos clientes A2A quem é um agente, onde contatá-lo, o que ele pode fazer, e como o acesso é protegido. Esta referência cobre cada campo v1.0 com tipos, requisitos, exemplos, e os erros que os validadores mais frequentemente detectam.
Como funciona a descoberta
Um cliente A2A busca o Agent Card a partir do URI well-known, avalia skills, capacidades, e requisitos de segurança em relação à sua tarefa, e então chama a interface preferida — a primeira entrada em supportedInterfaces. Se capabilities.extendedAgentCard for true, clientes autenticados podem solicitar um Agent Card mais rico através da operação GetExtendedAgentCard.
A especificação registra /.well-known/agent-card.json como o local padrão. Implantações v0.x mais antigas usavam /.well-known/agent.json, por isso nosso validador verifica ambos.
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}Referência de campos
As marcações de obrigatoriedade seguem as definições protobuf da v1.0 na especificação oficial. Links de âncora tornam cada campo citável a partir de issues, revisões, e saídas de CI.
Nome legível por humanos do agente.
Exibido em listagens de marketplace e interfaces de cliente. Mantenha-o curto e específico — os clientes o usam como rótulo principal ao comparar agentes candidatos.
Erro comum: Usar um nome genérico como "AI Assistant" que não dá aos sistemas de roteamento nada para diferenciar.
"name": "Agente planejador de rotas geoespaciais"
O que o agente faz e quando outro agente deveria chamá-lo.
Este é o principal sinal de texto livre tanto para integradores humanos quanto para roteadores baseados em LLM decidindo se seu agente se encaixa em uma tarefa. Declare o domínio da tarefa, habilidades principais, e limites.
Erro comum: Descrições de uma linha com menos de 20 caracteres. Roteadores não conseguem corresponder o que você não descreve.
"description": "Fornece planejamento avançado de rotas, análise de tráfego e serviços de geração de mapas personalizados."
Lista ordenada de endpoints e bindings de protocolo. A primeira entrada é preferida.
Novo na v1.0: substitui os antigos campos de nível superior url, preferredTransport, e additionalInterfaces. Cada entrada declara sua própria url, protocolBinding (JSONRPC, GRPC, HTTP+JSON, ou uma URI de binding personalizada), protocolVersion, e uma chave opcional de roteamento de tenant — assim um agente pode servir múltiplas versões de protocolo e transportes simultaneamente.
Erro comum: Declarar um binding que o servidor na verdade não serve naquela URL — a especificação exige que cada entrada seja precisa.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Quem opera o agente: organização e site.
Sinal de confiança para marketplaces e auditorias corporativas. A v1.0 renomeou o campo name para organization; url é obrigatório dentro do objeto quando presente.
Erro comum: Ainda usar provider.name (pré-1.0). Validadores que leem Agent Cards v1.0 não o reconhecerão.
"provider": {
"organization": "Exemplo Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}A versão do próprio agente, não do protocolo.
Permite que os clientes detectem quando um Agent Card mudou materialmente e reavaliem a compatibilidade. Siga seu próprio esquema de lançamento, tipicamente semver.
Erro comum: Confundir isso com a versão do protocolo A2A — que agora reside em cada entrada de supportedInterfaces.
"version": "1.2.0"
Link para documentação legível por humanos do agente.
Dá aos integradores um lugar para ler o contrato completo da API, limites de taxa, e termos que não pertencem a um documento de descoberta.
Erro comum: Apontar para uma página inicial de marketing em vez de documentação técnica.
"documentationUrl": "https://docs.example.com/agent"
Flags de recursos do protocolo: streaming, pushNotifications, extensions, extendedAgentCard.
Clientes NÃO DEVEM chamar recursos que você não declarou — chamadas de streaming não declaradas retornam erros. extendedAgentCard: true anuncia um Agent Card autenticado mais rico através da operação GetExtendedAgentCard. A v1.0 removeu stateTransitionHistory.
Erro comum: Declarar streaming: true quando o servidor não tem endpoint de streaming. Clientes o chamarão e falharão.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Esquemas de autenticação nomeados: chave de API, autenticação HTTP, OAuth 2.0, OpenID Connect, ou TLS mútuo.
Cada esquema nomeado envolve um objeto de esquema concreto (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). Os clientes descobrem como se autenticar a partir daqui — as credenciais em si são sempre obtidas fora de banda.
Erro comum: Incorporar uma chave de API ou token real no Agent Card. Um Agent Card é um documento público.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Quais esquemas declarados (e escopos) são necessários para chamar o agente.
Cada entrada mapeia um nome de esquema de securitySchemes para os escopos que ele precisa, espelhando o padrão de requisito de segurança do OpenAPI. Omita ambos os campos completamente para agentes intencionalmente públicos.
Erro comum: Declarar securitySchemes mas sem requisitos de security, deixando os clientes adivinharem se a autenticação é imposta.
"security": [{ "google": ["openid", "profile", "email"] }]Tipos de mídia que o agente aceita em todas as skills.
Tipos MIME padrão como text/plain, application/json, ou image/png. Skills individuais podem substituir com seus próprios inputModes.
Erro comum: Omitir o campo. É obrigatório na v1.0 — os clientes precisam dele para moldar as requisições.
"defaultInputModes": ["application/json", "text/plain"]
Tipos de mídia que o agente retorna em todas as skills.
Diz aos chamadores se devem esperar prosa, JSON estruturado, imagens, ou arquivos. Skills podem substituir por skill com outputModes.
Erro comum: Listar apenas text/plain quando o agente na verdade retorna artefatos estruturados.
"defaultOutputModes": ["application/json", "image/png"]
As habilidades concretas nas quais o agente provavelmente terá sucesso.
Cada skill requer id, name, description, e tags; examples, modos por skill, e segurança por skill são opcionais. Skills são a unidade de descoberta — roteadores combinam tarefas contra elas, então limite cada uma a um único limite de tarefa.
Erro comum: Skills sem tags. Tags se tornaram obrigatórias na v1.0 e impulsionam a correspondência em nível de skill.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Otimizador de rotas com reconhecimento de tráfego",
"description": "Calcula rotas de condução ideais usando tráfego em tempo real...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Planeje uma rota de A a B evitando pedágios."]
}]Assinaturas JSON Web que provam que o Agent Card foi emitido pelo provedor.
Cada assinatura carrega um cabeçalho JWS protegido base64url e um valor de assinatura, calculado sobre o Agent Card canonicalizado RFC 8785 (JCS). Os clientes DEVERIAM verificar pelo menos uma assinatura antes de confiar em um Agent Card obtido da web aberta.
Erro comum: Assinar o cartão e depois editar qualquer campo — mesmo mudanças de valor insignificantes em espaços em branco invalidam o JWS.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL para um ícone que representa o agente.
Usado por catálogos e interfaces de cliente. Sirva-o via HTTPS a partir de um local estável.
Erro comum: Vincular um ícone em um domínio diferente e não confiável que pode mudar sem aviso sob sua listagem.
"iconUrl": "https://agent.example.com/icon.png"
Migração de versão
Se o seu Agent Card ainda tem um url ou preferredTransport de nível superior, ele é anterior à v1.0. O validador sinaliza cada um deles automaticamente.
| Campo v0.x | Substituição v1.0 | Por que mudou |
|---|---|---|
| url | supportedInterfaces[0].url | O endpoint preferido agora é simplesmente a primeira entrada de interface. |
| preferredTransport | supportedInterfaces[] ordering | A preferência é expressa pela ordem do array em vez de um campo separado. |
| additionalInterfaces | supportedInterfaces[] | Todas as interfaces residem em um único array ordenado. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Cada interface declara sua própria versão de protocolo, permitindo suporte multi-versão. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | Movido para o objeto capabilities; o RPC foi renomeado para GetExtendedAgentCard. |
| provider.name | provider.organization | Renomeado para clareza. |
| capabilities.stateTransitionHistory | — removed | Não faz parte da v1.0; modele comportamento equivalente como uma extensão se necessário. |
Boilerplate
Coloque essas interfaces em um cliente, servidor, ou verificação de CI para analisar e produzir Agent Cards com segurança de tipos. Elas espelham as definições protobuf no repositório oficial da especificação, na forma JSON camelCase em que os Agent Cards são publicados.
Construindo um Agent Card à mão em vez disso? O gerador produz exatamente essa forma.
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }Integridade
Como os Agent Cards são obtidos da web aberta, a v1.0 formaliza a assinatura: o Agent Card (menos o campo signatures e valores padrão) é canonicalizado com RFC 8785 JSON Canonicalization, depois assinado como um JWS. Os clientes devem verificar pelo menos uma assinatura — via o cabeçalho kid/jku ou um armazenamento de chaves confiável — antes de agir sobre um Agent Card. Múltiplas assinaturas suportam rotação de chaves.
Sirva o Agent Card em /.well-known/agent-card.json via HTTPS.
Cada entrada de supportedInterfaces é alcançável e fala o binding declarado.
Skills têm tags obrigatórias mais descrições com limites de tarefa claros.
As capabilities declaradas correspondem ao servidor — recursos não declarados devem retornar erros, os declarados devem funcionar.
securitySchemes descreve como se autenticar; nenhuma credencial aparece em qualquer lugar do Agent Card.
version é incrementado sempre que o conteúdo do Agent Card muda.
Um agente de suporte ao cliente com OAuth 2.0, streaming, e notificações push — todos os campos obrigatórios presentes. Mais padrões estão na biblioteca de exemplos.
{
"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"
]
}
]
}Perguntas frequentes
As mudanças de versão, campos de descoberta, e detalhes de publicação que decidem se um Agent Card passa na revisão.
A v1.0 consolidou url, preferredTransport, e additionalInterfaces em um único array ordenado supportedInterfaces onde cada entrada declara sua própria url, protocolBinding, e protocolVersion. supportsAuthenticatedExtendedCard foi movido para capabilities.extendedAgentCard, provider.name tornou-se provider.organization, tags de skill se tornaram obrigatórias, e assinaturas de Agent Card JWS foram formalizadas com canonicalização RFC 8785.
Não. Um Agent Card é um documento de descoberta para um agente. Ele resume identidade, interfaces, capabilities, skills, modos, provedor, e metadados de segurança, enquanto um schema de API completo descreve formas detalhadas de requisição e resposta. Ele desempenha o papel que um README ou uma visão geral OpenAPI desempenha para um serviço: o suficiente para decidir se e como chamá-lo.
name, description, supportedInterfaces, skills (com tags), defaultInputModes, defaultOutputModes, capabilities, provider, e metadados de segurança. Sistemas de roteamento combinam tarefas com sua description e tags de skill, depois usam interfaces e capabilities para planejar a chamada real.
Publique apenas skills que sejam seguras para descoberta não autenticada. Se um Agent Card privado mais rico for necessário, defina capabilities.extendedAgentCard como true e exponha skills sensíveis através da operação autenticada GetExtendedAgentCard.
No URI well-known https://{seu-dominio}/.well-known/agent-card.json, servido com o content type application/a2a+json (application/json também funciona na prática). Implementações anteriores usavam /.well-known/agent.json, então publicar ambos durante a transição é uma escolha pragmática.
Coloque o schema para trabalhar
Gere um Agent Card no formato v1.0 a partir dos detalhes do seu serviço, ou cole um Agent Card existente no validador para ver exatamente quais campos precisam de atenção.