Ao registrar manualmente agentes ou servidores do Protocolo de Contexto de Modelo (MCP) no
Agent Registry criando um recurso Service, você fornece arquivos de configuração
JSON que declaram os recursos deles. O Agent Registry valida
esses arquivos em relação às especificações de código aberto antes de indexá-los para que
os consumidores possam descobrir as
habilidades de A2A e as ferramentas de MCP
do agente. Use as seguintes estruturas e exemplos de JSON para formatar as especificações dos Cards de Agente e das ferramentas do MCP.
Esquema do card do agente
Ao registrar um agente compatível com A2A, o payload agent-card.json precisa seguir a especificação oficial do Agent2Agent (A2A).
O tamanho máximo do arquivo de especificação é de 150 KB.
Os campos de matriz skills são compatíveis com o índice da Pesquisa de palavras-chave.
O Registro de Agentes é compatível com as versões 1.0 e 0.3 do card do agente
A2A. Selecione uma
versão para ver o esquema JSON e as definições de campo:
Versão 1.0 (recomendada)
Para a versão 1.0 dos cards de agente A2A, o payload precisa seguir a especificação v1.0 oficial do A2A. Nessa especificação, você declara
endpoints de transporte em uma matriz supportedInterfaces:
{
"name": "string",
"description": "string",
"version": "string",
"supportedInterfaces": [
{
"url": "string",
"protocolBinding": "string",
"protocolVersion": "string",
"tenant": "string"
}
],
"capabilities": {
"streaming": false,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain"
],
"skills": [
{
"id": "string",
"name": "string",
"description": "string",
"tags": [
"string"
],
"examples": [
"string"
]
}
]
}
Definições dos campos
name: o nome legível por humanos do agente.description: um resumo de alto nível do propósito do agente.version: a versão do agente, por exemplo,1.0.0.supportedInterfaces: uma matriz de combinações de transporte e URL compatíveis. Cada interface contém o seguinte:url: o URL do endpoint em que essa interface é acessada.protocolBinding: a vinculação de protocolo compatível com esse URL, por exemplo,HTTP+JSON,JSONRPCouGRPC.protocolVersion: a versão do protocolo A2A que essa interface expõe, por exemplo,1.0.0.tenant(opcional): o identificador do proprietário do agente.
capabilities(opcional): especifica os recursos operacionais compatíveis, como os seguintes:extensions(opcional): uma matriz de extensões de protocolo.streaming(opcional): um booleano que indica se o agente é compatível com respostas de streaming.pushNotifications(opcional): um booleano que indica se as notificações push são compatíveis com atualizações de tarefas.extendedAgentCard(opcional): um booleano que indica se o agente fornece um card estendido quando autenticado.
defaultInputModes(opcional): uma matriz de tipos MIME aceitos como entrada.defaultOutputModes(opcional): uma matriz de tipos MIME produzidos como saída.skills: uma matriz de habilidades descritivas de A2A que o agente possui:id: um identificador programático exclusivo para a skill de A2A.name: um nome legível por humanos para a habilidade de A2A.description: uma explicação detalhada do que a habilidade de A2A faz.tags: uma matriz de strings de palavras-chave usadas para categorizar a habilidade de A2A.examples: uma matriz de exemplos de comandos ou cenários que essa habilidade de A2A processa.
Versão 0.3
Para a versão 0.3 dos cards de agente A2A, o payload precisa seguir a
especificação v0.3.0. Nessa especificação, o URL de inferência principal e a versão do protocolo são declarados como campos de nível superior:
{
"name": "string",
"description": "string",
"version": "string",
"protocolVersion": "string",
"url": "string",
"skills": [
{
"id": "string",
"name": "string",
"description": "string",
"tags": [
"string"
],
"examples": [
"string"
]
}
],
"capabilities": {
"streaming": false,
"pushNotifications": false,
"stateTransitionHistory": false
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain"
]
}
Definições dos campos
name: o nome legível por humanos do agente.description: um resumo de alto nível do propósito do agente.version: a versão do agente, por exemplo,1.0.2.protocolVersion: a versão do protocolo A2A que o agente implementa. Como a versão1.0descontinua esse campo de nível superior, o valor precisa ser0.3ou qualquer versão de patch0.3, como0.3.1, para esse esquema.url: o URL do endpoint em que o agente pode ser acessado.capabilities(opcional): um objeto que especifica os recursos operacionais compatíveis com o agente, comostreaming,pushNotificationsoustateTransitionHistory.defaultInputModes(opcional): uma matriz de strings que define os tipos MIME padrão que o agente aceita como entrada, por exemplo,["text/plain"].defaultOutputModes(opcional): uma matriz de strings que define os tipos MIME padrão que o agente produz como saída, por exemplo,["text/plain"].skills: uma matriz de habilidades descritivas de A2A que o agente possui:id: um identificador programático exclusivo para a skill de A2A.name: um nome legível por humanos para a habilidade de A2A.description: uma explicação detalhada do que a habilidade de A2A faz.tags: uma matriz de strings de palavras-chave usadas para categorizar a habilidade de A2A.examples: uma matriz de exemplos de comandos ou cenários que essa habilidade de A2A processa.
Esquema da ferramenta MCP
Ao registrar um servidor MCP, o payload toolspec.json precisa incluir uma lista de ferramentas que aderem ao esquema de objeto Tool do MCP.
O payload esperado é um objeto JSON com um único campo tools, exatamente como
retornado pelas
ferramentas padrão do MCP ou pela solicitação de lista.
O tamanho máximo desse arquivo de especificação é de 150 KB.
{
"tools": [
{
"name": "string",
"description": "string",
"inputSchema": {
"type": "object",
"properties": {}
},
"annotations": {
"title": "string",
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": false,
"openWorldHint": true
},
"_meta": {
"com.googleapis.iap/PolicyHints": {
"authorization": {
"toolDisabled": false,
"hitlMode": "HITL_MODE_ALWAYS"
}
}
}
}
]
}
Definições dos campos
tools: uma matriz de ferramentas fornecidas pelo servidor:name: o identificador programático da ferramenta.description: uma explicação legível por humanos sobre a finalidade da ferramenta.inputSchema: um objeto de esquema JSON que define os parâmetros esperados para a ferramenta.annotations: dicas comportamentais que orientam como os agentes orquestradores interagem com a ferramenta:title: um título legível para humanos para a ferramenta.readOnlyHint: se fortrue, a ferramenta só vai recuperar dados e não vai modificar o ambiente. O padrão éfalse.destructiveHint: se fortrue, a ferramenta vai realizar operações que podem causar mudanças permanentes. O padrão étrue.idempotentHint: se fortrue, chamar a ferramenta repetidamente não terá efeito adicional. O padrão éfalse.openWorldHint: setrue, a ferramenta interage com sistemas externos. O padrão étrue.
_meta(opcional): metadados no nível do protocolo que seguem a especificação do Protocolo de Contexto de Modelo (MCP) para anexar metadados estruturados a ferramentas. Como oannotationspadrão é um objeto fechado limitado a dicas predefinidas, o_metafornece um contêiner extensível para metadados adicionais, mantendo a compatibilidade com clientes MCP padrão.Para evitar conflitos de nomenclatura entre provedores, as chaves de nível superior em
_metausam a notação de domínio reverso. O Agent Registry valida_metaem relação aoapphub.googleapis.com/McpServeresquema de metadados estendido e oferece suporte ao seguinte namespace:com.googleapis.iap/PolicyHints(opcional): dicas de política avaliadas pelo Identity-Aware Proxy (IAP) e pelo Gateway de Agente para aplicar controles de autorização de ferramentas e human-in-the-loop (HITL):authorization(opcional): configuração de autorização para a ferramenta:toolDisabled(opcional): um booleano que indica se a ferramenta está desativada para invocação. Defina comotruepara desativar a ferramenta. O padrão éfalse, o que significa que a ferramenta é ativada quando você omite esse campo.hitlMode(opcional): uma string que especifica o modo de execução human-in-the-loop (HITL) para a ferramenta:HITL_MODE_UNSPECIFIED: o modo HITL não foi especificado.HITL_MODE_DISABLED: a ferramenta é executada sem exigir aprovação humana interativa.HITL_MODE_ALWAYS: a ferramenta sempre exige aprovação humana interativa antes da execução.HITL_MODE_IF_UNSAFE: a ferramenta requer aprovação humana interativa apenas quando a operação é avaliada como não segura.