O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Usar o registro manual

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

Aviso:esse recurso não está disponível nas multirregiões us e eu. É preciso usar uma região com disponibilidade ou o local global. Para mais informações, consulte Locais do 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 agentes manualmente no Registro de agentes, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para registrar agentes no Agent Registry: Editor da API Agent Registry (roles/agentregistry.editor)
Para o registro entre projetos, acesse os metadados do agente em um projeto remoto: Leitor da API Agent Registry (roles/agentregistry.viewer)

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.

Você não precisa de outras permissões se o endpoint do agente ou o cartão do agente puder ser acessado usando URLs públicos padrão ou autenticado com credenciais pré-configuradas.

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 A2A disponíveis do agente para descoberta.

Siga estas etapas para registrar o agente:

Console

No console do Google Cloud , acesse Registro de agentes:

Acessar o Agent Registry
No seletor de projetos, escolha o projeto do Google Cloud em que você configurou o Agent Registry.
Selecione a guia Agentes.
Clique em Adicionar agente.
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.
Escolha uma das seguintes opções:
- Para registrar o agente usando o URL do card dele, 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 cartão do agente, selecione a guia Colar JSON e cole todo o conteúdo do arquivo agent-card.json.
Clique em Salvar.

gcloud

As flags de especificação usadas determinam a qual coleção de recursos seu serviço pertence. Para um mapeamento completo de flags para coleções de recursos, consulte Recursos da API.

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 por humanos que você quer dar ao seu agente, por exemplo, Support Agent.

Terraform

O bloco de especificação que você configura, por exemplo, agent_spec, determina a qual coleção de recursos seu serviço pertence. Para um mapeamento completo de especificações para coleções de recursos, consulte Recursos da API.

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 a carga útil 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 por humanos 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 de A2A pesquisáveis, a menos que adotem o protocolo A2A.

Para registrar um agente remoto que não implementa a especificação A2A, crie um recurso Service configurado com --agent-spec-type=no-spec. Em seguida, o Agent Registry gera um recurso Agent correspondente na coleção agents.

Usar --agent-spec-type=no-spec registra um agente, não um destino de API de destino. Se você quiser registrar um destino de API externa a que os agentes se conectam, registre um endpoint. Para instruções, consulte Registrar endpoints.

Siga estas etapas para registrar o agente:

Console

No console do Google Cloud , acesse Registro de agentes:

Acessar o Agent Registry
No seletor de projetos, escolha o projeto do Google Cloud em que você configurou o Agent Registry.
Selecione a guia Agentes.
Clique em Adicionar agente.
No painel Detalhes do agente, insira os seguintes detalhes:
- Tipo: selecione Não A2A.
- Nome: insira um nome de exibição legível por humanos para o agente, como Travel Agent.
- Descrição: insira uma descrição das funcionalidades 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.
Clique em Salvar.

gcloud

As flags de especificação usadas determinam a qual coleção de recursos seu serviço pertence. Para um mapeamento completo de flags para coleções de recursos, consulte Recursos da API.

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 por humanos 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 de 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 por humanos 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.

Registrar um agente de outro projeto

Se a organização implantar agentes em vários projetos do Google Cloud e usar um gateway de agente central para controlar o tráfego de saída, é possível 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 vários projetos, revise o seguinte:

Locais compatíveis: a instância do Agent Registry, o Gateway de Agente e os Agent Endpoints precisam estar na mesma região geográfica ou no local global.
Limitação da descoberta automática: não há suporte para a descoberta automática entre projetos. Você precisa registrar cada agente remoto manualmente.
Gerenciamento do ciclo de vida: as entradas manuais no registro de agentes não são atualizadas ou excluídas automaticamente quando ocorrem mudanças no projeto remoto. Você precisa 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 só é compatível com gateways de saída (agente para qualquer lugar). 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

No console do Google Cloud , acesse Registro de agentes:

Acessar o Agent Registry
No seletor de projetos, escolha o projeto de governança central Google Cloud em que você quer registrar o agente.
Selecione a guia Agentes.
Clique em Adicionar agente.
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.
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 que não são A2A, insira o URL do endpoint do agente remoto.
Clique em Salvar.

gcloud

As flags de especificação usadas determinam a qual coleção de recursos seu serviço pertence. Para um mapeamento completo de flags para coleções de recursos, consulte Recursos da API.

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 seu 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 por humanos 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 seu agente no registro, por exemplo, remote-support-agent.
DISPLAY_NAME: o nome legível por humanos 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 Registro de agentes processou o Service e criou o recurso Agent correspondente:

Console

No console do Google Cloud , acesse Registro de agentes:

Acessar o Agent Registry
No seletor de projetos, escolha o projeto do Google Cloud em que você configurou o Agent Registry.
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 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

Referencie 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

Saiba como gerenciar agentes registrados.
Saiba mais sobre o registro automático, o método recomendado para registrar agentes implantados em tempos de execução gerenciados.

Usar o registro manual Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Funções exigidas

Registrar um agente compatível com A2A

Console

gcloud

Terraform

Registrar um agente REST padrão

Console

gcloud

Terraform

Registrar um agente de outro projeto

Considerações sobre o registro entre projetos

Registrar o agente remoto

Console

gcloud

Terraform

Verificar o registro

Console

gcloud

Terraform

A seguir

Usar o registro manual