Usar o registro manual

É necessário fazer o registro manual no Agent Registry para agentes hospedados fora do Google Cloud ou executados em runtimes não compatíveis. Este documento mostra como registrar agentes manualmente no Agent Registry.

Antes de começar

Antes de começar, configure o Agent Registry. Você precisa do ID do projeto para realizar essas tarefas.

Para usar os comandos da Google Cloud CLI neste documento, verifique se você configurou seu ambiente da CLI gcloud.

Funções exigidas

Para receber as permissões necessárias para registrar manualmente agentes no Registro de agentes, peça ao administrador para conceder a você o papel do IAM de Editor da API Agent Registry (roles/agentregistry.editor) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Registrar um agente compatível com A2A

Se o agente remoto implementar a especificação Agent2Agent (A2A), direcione o registro de agente para o payload agent-card.json do agente. O registro sincroniza automaticamente o card do agente e indexa as habilidades disponíveis do agente para descoberta.

Siga estas etapas para registrar o agente:

Console

  1. No console do Google Cloud , acesse Registro de agentes:

    Acessar o Agent Registry

  2. No seletor de projetos, escolha o projeto Google Cloud em que você configurou o Agent Registry.

  3. Selecione a guia Agentes.

  4. Clique em Adicionar agente.

  5. No painel Detalhes do agente, insira os seguintes detalhes:

    • Tipo: selecione A2A.
    • Região: selecione a localização geográfica em que você quer registrar o agente.

  6. Escolha uma das seguintes opções:

    • Para registrar o agente usando o URI do recurso, selecione a guia Do URI e insira um URL válido no campo URI. Em seguida, clique em Importar para acessar o card do agente no URL.
    • Para copiar e colar o conteúdo do card do agente, selecione a guia Colar JSON e cole todo o conteúdo do arquivo agent-card.json.

  7. Clique em Salvar.

gcloud

Para registrar um agente A2A, salve o card do agente como um arquivo JSON local, por exemplo, agent-card.json, e faça o seguinte:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=agent-card.json

O tamanho máximo do arquivo de especificação é de 10 KB.

Substitua:

  • AGENT_NAME: o nome que você quer dar ao agente, por exemplo, my-support-agent.
  • PROJECT_ID: o ID do projeto.
  • REGION: a região em que você quer registrar o agente. Se você não quiser usar uma região específica, use o valor global.
  • DISPLAY_NAME: o nome legível que você quer dar ao seu agente, por exemplo, Support Agent.

Terraform

Para registrar um agente compatível com A2A, configure o recurso google_agent_registry_service. Especifique o bloco agent_spec com o tipo A2A_AGENT_CARD e o content que representa o payload JSON do card do agente:

resource "google_agent_registry_service" "a2a_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"

  agent_spec {
    type    = "A2A_AGENT_CARD"
    content = jsonencode({
      schemaVersion = "v1"
      displayName   = "DISPLAY_NAME"
      description   = "A custom support agent registered using Terraform."
      skills = [
        {
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
        }
      ]
    })
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.a2a_agent.registry_resource
}

Substitua:

  • REGION: a região em que você registra o agente.
  • AGENT_NAME: o nome exclusivo que você quer dar ao agente, por exemplo, my-support-agent.
  • DISPLAY_NAME: o nome legível que você quer dar ao seu agente, por exemplo, Support Agent.

Registrar um agente REST padrão

Os agentes REST padrão são detectáveis por nome e descrição, mas não têm habilidades pesquisáveis, a menos que adotem o protocolo A2A.

Se você quiser registrar um agente remoto que não implementa a especificação A2A, como um endpoint de API REST ou SaaS padrão, a API Agent Registry cria um recurso Service sem especificação de protocolo de agente.

Siga estas etapas para registrar o agente:

Console

  1. No console do Google Cloud , acesse Registro de agentes:

    Acessar o Agent Registry

  2. No seletor de projetos, escolha o projeto Google Cloud em que você configurou o Agent Registry.

  3. Selecione a guia Agentes.

  4. Clique em Adicionar agente.

  5. No painel Detalhes do agente, insira os seguintes detalhes:

    • Tipo: selecione Não A2A.
    • Nome: insira um nome de exibição legível para o agente, como Travel Agent.
    • Descrição: insira uma descrição das capacidades do agente, como A test agent that plans travel itineraries.
    • Região: selecione a localização geográfica em que você quer registrar o agente.
    • Endpoint: insira o endpoint em que o agente está hospedado.

  6. Clique em Salvar.

gcloud

Você também pode fornecer a interface de endpoint HTTP/JSON definida com a flag --interfaces para que o registro estabeleça uma conexão com o agente.

Para registrar um agente REST padrão, faça o seguinte:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

Substitua:

  • AGENT_NAME: o nome que você quer dar ao agente, por exemplo, my-remote-rest-agent.
  • PROJECT_ID: o ID do projeto.
  • REGION: a região do registro.
  • DISPLAY_NAME: o nome legível que você quer dar ao seu agente, por exemplo, Remote REST Agent.
  • ENDPOINT_URL: o URL do endpoint de API do agente. Por exemplo, https://api.remote-service.com/v1/agents/1234.
  • PROTOCOL: a vinculação de protocolo para o endpoint. Os valores válidos são HTTP_JSON, GRPC ou JSONRPC.

Terraform

Para registrar um agente REST padrão, configure o recurso google_agent_registry_service com agent_spec definido como o tipo NO_SPEC e defina as conexões de interface do endpoint:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "A standard REST agent registered using Terraform."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.rest_agent.registry_resource
}

Substitua:

  • REGION: a região em que você registra o agente.
  • AGENT_NAME: o nome exclusivo que você quer dar ao agente, por exemplo, my-remote-rest-agent.
  • DISPLAY_NAME: o nome legível que você quer dar ao seu agente, por exemplo, Remote REST Agent.
  • ENDPOINT_URL: o URL do endpoint de API do agente. Por exemplo, https://api.remote-service.com/v1/agents/1234.
  • PROTOCOL: a vinculação de protocolo para o endpoint. Os valores válidos são HTTP_JSON, GRPC ou JSONRPC.

Verificar o registro

Depois de registrar o agente, verifique se o Agent Registry processou o Service e criou o recurso Agent correspondente:

Console

  1. No console do Google Cloud , acesse Registro de agentes:

    Acessar o Agent Registry

  2. No seletor de projetos, escolha o projeto Google Cloud em que você configurou o Agent Registry.

  3. Selecione a guia Agentes.

    A página precisa mostrar uma lista de todos os agentes registrados e os detalhes deles.

gcloud 

gcloud agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION

Se você tiver vários agentes ou quiser confirmar o registro de um único agente, filtre a lista pelos metadados dele:

gcloud agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

Substitua:

  • PROJECT_ID: o ID do projeto.
  • REGION: a região em que você quer registrar o agente. Se você não quiser usar uma região específica, use o valor global.
  • FILTER_EXPRESSION: a expressão de filtro para os agentes que você quer filtrar. Por exemplo, para filtrar por nome de exibição, use displayName='DISPLAY_NAME'. Para filtrar pelo identificador (URN) globalmente exclusivo, use agentId='urn:agent:AGENT_URN'.

Terraform

Faça referência ao agente registrado em outras configurações do Terraform usando a fonte de dados google_agent_registry_agent:

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  filter = "displayName=\"DISPLAY_NAME\""
}

output "agent_urn" {
  value = data.google_agent_registry_agent.my_agent.urn
}

Substitua:

  • REGION: a região do registro.
  • DISPLAY_NAME: o nome de exibição legível do agente.

A seguir