Usar o registro manual

É necessário fazer o registro manual no Agent Registry para agentes hospedados fora do Google Cloud, executados em ambientes de execução não compatíveis ou implantados em diferentes Google Cloud projetos. 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 o ambiente da CLI gcloud.

Funções exigidas

Para ter as permissões necessárias para registrar agentes manualmente no Agent Registry, peça ao administrador para conceder a você os seguintes papéis do IAM 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 com papéis personalizados ou outros papéis predefinidos.

Você não precisa de outras permissões se o endpoint ou o card do agente estiver acessível usando URLs públicos padrão ou autenticado por credenciais pré-configuradas.

Registrar um agente compatível com A2A

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

Siga estas etapas para registrar o agente:

Console

  1. No Google Cloud console, acesse o Agent Registry:

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o Google Cloud projeto 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 seu URI de recurso, selecione a guia Do URI e insira um URL válido no campo URI. Em seguida, clique em Importar para receber o card do agente do 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 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 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 A2A 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 do agente.

Siga estas etapas para registrar o agente:

Console

  1. No Google Cloud console, acesse o Agent Registry:

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o Google Cloud projeto 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 dos recursos 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

Opcionalmente, você 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 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 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.

Registrar um agente de outro projeto

Se a organização implantar agentes em vários Google Cloud projetos e usar um gateway de agente central Agent Gateway para governar o tráfego de saída, você poderá registrar agentes de projetos de spoke ou de carga de trabalho no catálogo central do Agent Registry.

Como o registro automático só descobre recursos criados no mesmo projeto, é necessário registrar manualmente cada agente remoto no registro do projeto de governança central.

Considerações sobre o registro entre projetos

Antes de registrar agentes em projetos, revise o seguinte:

  • Locais compatíveis: a instância do Agent Registry, o gateway de agente e os endpoints do agente precisam residir na mesma região geográfica ou no local global.
  • Limitação de descoberta automática: a descoberta automática entre projetos é indisponível. É necessário registrar manualmente cada agente remoto.
  • Gerenciamento do ciclo de vida: as entradas manuais no Agent Registry não são atualizadas ou excluídas automaticamente quando ocorrem mudanças no projeto remoto. É necessário gerenciar o ciclo de vida dessas entradas no registro central quando os agentes remotos são modificados ou removidos.
  • Somente modo de saída: a governança entre projetos com o gateway de agente é compatível apenas com gateways de agente para qualquer lugar (saída). Os gateways de entrada de cliente para agente exigem que o agente e o gateway estejam no mesmo projeto.

Registrar o agente remoto

Para registrar manualmente um agente de outro projeto, siga estas etapas:

Console

  1. No Google Cloud console, acesse o Agent Registry:

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o projeto de governança central Google Cloud em que você quer registrar o agente.

  3. Selecione a guia Agentes.

  4. Clique em Adicionar agente.

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

    • Tipo: selecione A2A se o agente remoto implementar o protocolo A2A ou Não A2A para um endpoint REST padrão.
    • Região: selecione a região que corresponde à implantação do gateway central e do agente remoto.

  6. Forneça o endpoint do agente:

    • Para agentes A2A, selecione Do URI e insira o URL do card do agente remoto ou selecione Colar JSON e cole o conteúdo agent-card.json.
    • Para agentes não A2A, insira o URL do endpoint do agente remoto.

  7. Clique em Salvar.

gcloud

  • Agente A2A: para registrar um agente A2A de outro projeto usando a CLI gcloud, execute o seguinte comando no projeto de governança central:
gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@agent-card.json
  • Agente REST: para registrar um agente REST padrão de outro projeto, execute o seguinte comando no projeto de governança central:
gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=REMOTE_ENDPOINT_URL,protocolBinding=PROTOCOL

Substitua:

  • AGENT_NAME: o nome do agente no registro central, por exemplo, remote-support-agent.
  • CENTRAL_PROJECT_ID: o ID do projeto de governança central.
  • REGION: a região em que você registra o agente.
  • DISPLAY_NAME: o nome legível do agente, por exemplo, Remote Support Agent.
  • REMOTE_ENDPOINT_URL: o URL do endpoint do agente em execução no projeto remoto, por exemplo, https://<var>AGENT_SERVICE_NAME</var>-<var>HASH</var>.<var>REGION</var>.run.app.
  • 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 remoto em um projeto de governança central usando o Terraform, configure o recurso google_agent_registry_service e especifique o projeto central:

resource "google_agent_registry_service" "remote_agent" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Remote agent registered from project REMOTE_PROJECT_ID."

  agent_spec {
    type = "NO_SPEC"
  }

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

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

Substitua:

  • CENTRAL_PROJECT_ID: o ID do projeto de governança central.
  • REGION: a região em que você registra o agente.
  • AGENT_NAME: o nome exclusivo do agente no registro, por exemplo, remote-support-agent.
  • DISPLAY_NAME: o nome legível do agente, por exemplo, Remote Support Agent.
  • REMOTE_PROJECT_ID: o ID do projeto em que o agente está hospedado.
  • REMOTE_ENDPOINT_URL: o URL do endpoint do agente em execução no projeto remoto.
  • 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 Google Cloud console, acesse o Agent Registry:

    Acessar o Agent Registry

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

  3. Selecione a guia Agentes.

    A página mostra 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 do agente:

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, você pode usar displayName='DISPLAY_NAME'. Para filtrar pelo identificador globalmente exclusivo (URN), use agentId='urn:agent:AGENT_URN'.

Terraform

Consulte o 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