Configurar o Agent Registry

Para registrar e descobrir seus agentes de IA, servidores do Protocolo de Contexto de Modelo (MCP), habilidades independentes e endpoints no Agent Registry, é necessário ativar a API Agent Registry no seu projeto do Google Cloud . O projeto em que você ativa o Agent Registry serve como seu projeto de governança.

É possível configurar o Registro de Agentes em um único projeto de governança ou em vários projetos, configurando um limite de gerenciamento em que um projeto de gerenciamento central serve como seu projeto de governança.

Antes de começar

Configure o Agent Registry em um único projeto ou em vários projetos:

• Projeto único: descubra e gerencie agentes, servidores MCP, habilidades e endpoints em um único projeto de governança do Google Cloud . Use um projeto atual ou crie um projeto, ative a API Agent Registry e conceda permissões.
• Vários projetos (limite de gerenciamento): centralize a descoberta e a governança em vários projetos membros na sua hierarquia de recursos doGoogle Cloud associando um limite de gerenciamento a um projeto de gerenciamento. Defina um projeto do Google Cloud existente como seu projeto de gerenciamento ou deixe que o Resource Manager crie um para você, ative a API Resource Manager, configure um limite de gerenciamento e conceda permissões.

Funções exigidas

Para receber as permissões necessárias para configurar o Agent Registry, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto do Google Cloud :

• Ativar a API Agent Registry: Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin)
• Conceder papéis para usar a API Agent Registry: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin)
• Acesso total aos recursos da API Agent Registry: Administrador da API Agent Registry (roles/agentregistry.admin)

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.

Configurar o ambiente da Google Cloud CLI

Se você planeja usar a CLI gcloud para o Agent Registry, siga estas etapas:

1. No console do Google Cloud , ative o Cloud Shell.

   Ativar o Cloud Shell

   Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

2. Atualize a CLI gcloud para a versão mais recente com o comando gcloud components update:

   gcloud components update
   

3. Se você planeja usar os recursos de pré-lançamento, instale o componente alpha com o comando gcloud components install:

   gcloud components install alpha
   

Ativar a API Agent Registry

• Para um único projeto: ative a API Agent Registry no seu projeto de governança. Depois de ativar a API e conceder permissões, você poderá começar a registrar e descobrir agentes nesse projeto. Não é necessário configurar um limite de gerenciamento.
• Para vários projetos (limite de gerenciamento): ative a API Resource Manager no projeto usado para executar comandos de configuração. Quando você configura um limite de gerenciamento para vários projetos e cria a configuração de capacidade, o Resource Manager ativa automaticamente a API Agent Registry no seu projeto de gerenciamento.

Use o ID do projeto para ativar as APIs:

Console

Para um único projeto, ative a API Agent Registry no seu projeto:

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

Para vários projetos (limite de gerenciamento), ative a API Resource Manager no projeto usado para configuração:

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

gcloud

• Para um único projeto, ative a API Agent Registry no seu projeto com o comando gcloud services enable:

  gcloud services enable agentregistry.googleapis.com \
      --project=PROJECT_ID
  

• Para vários projetos (limite de gerenciamento), ative a API Resource Manager no projeto que você usa para configuração:

  gcloud services enable cloudresourcemanager.googleapis.com \
      --project=PROJECT_ID
  

Substitua PROJECT_ID pelo ID do projeto de governança independente ou pelo projeto que você quer usar como o projeto de gerenciamento do limite de gerenciamento.

Observação: se você integrar o Agent Registry ao Agent Gateway para aplicação de políticas, também será necessário ativar a API Identity-Aware Proxy no projeto. O gateway usa a API Identity-Aware Proxy para autenticar e autorizar o tráfego de saída dos seus agentes para destinos externos.

Configurar um limite de gerenciamento para vários projetos

Visualizar

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para usar o Agent Registry em vários projetos do Google Cloud , configure um limite de gerenciamento. Um limite de gerenciamento agrupa um ou mais projetos de membro do Google Cloud em um projeto de gerenciamento central que serve como seu projeto de governança para que você possa descobrir e governar agentes de IA, servidores MCP e ferramentas em todos os projetos.

Você define um limite de gerenciamento no Resource Manager. Para instruções detalhadas, consulte Configurar limites de gerenciamento na documentação do Resource Manager.

Para uma visão geral da arquitetura de como os recursos BoundaryConfig, Boundary e CapabilityConfig funcionam juntos, consulte Limites entre projetos.

Quando você cria um recurso CapabilityConfig com agent-management, o Resource Manager ativa automaticamente agentregistry.googleapis.com no projeto de gerenciamento. Depois de estabelecer o limite de gerenciamento:

1. Se necessário para operações locais em projetos de membros individuais, ative a API Agent Registry nesses projetos.
2. Conceda os papéis e as permissões necessários a usuários e contas de serviço no projeto de gerenciamento.

Quando você lista ou pesquisa agentes ou servidores MCP em um local no projeto de gerenciamento, o Agent Registry agrega e retorna recursos descobertos automaticamente nesse local de todos os projetos membros no limite, além de todos os recursos Service registrados criados diretamente nesse local no projeto de gerenciamento. Cada nome de recurso retornado preserva o ID do componente e usa o projeto especificado na solicitação.

Conceder permissões

Para visualizar e gerenciar recursos no Agent Registry, é necessário conceder aos usuários as permissões apropriadas do Identity and Access Management (IAM).

Conceda aos usuários um ou mais dos seguintes papéis do Agent Registry:

• Leitor da API Agent Registry (roles/agentregistry.viewer): visualizar e pesquisar agentes, servidores MCP, ferramentas, habilidades independentes, revisões de habilidades, editores, endpoints e vinculações.
• Editor da API Agent Registry (roles/agentregistry.editor): visualizar e editar recursos do Agent Registry, incluindo o registro, a atualização e a exclusão de agentes, servidores MCP, ferramentas, endpoints, habilidades independentes e revisões de habilidades.
• Administrador da API Agent Registry (roles/agentregistry.admin): realiza todas as ações em recursos do Agent Registry, incluindo o registro e o gerenciamento de agentes, servidores MCP, ferramentas, endpoints, habilidades independentes, revisões de habilidades, vinculações e políticas do IAM de habilidades.
• Usuário do Agent Registry (roles/agentregistry.user): visualizar todos os recursos do Agent Registry e criar, atualizar e excluir habilidades independentes e revisões de habilidades sem acesso de edição a agentes, servidores MCP ou endpoints.

Para saber como conceder papéis do IAM em um projeto, consulte Gerenciar o acesso a projetos, pastas e organizações.

Observação: o Agent Registry e o Gateway de Agente têm suporte limitado para a federação de identidade de colaboradores. Se você encontrar erros de carregamento ou autorização no console do Google Cloud , acesse o serviço com uma Conta do Google padrão gerenciada pelo Cloud Identity ou pelo Google Workspace.

Mudar o projeto do Agent Registry

Se você quiser mudar o projeto em que usa o Agent Registry e remover as dependências do projeto antigo, desative a API Agent Registry no projeto antigo. Depois de desativar a API Agent Registry no projeto antigo, é possível ativá-la em outro projeto. Seus dados não são migrados, e você precisa recriar os recursos nesse novo projeto.

Desativar a API Agent Registry

Se você não quiser mais usar o Agent Registry, desative a API Agent Registry no projeto:

Console

1. No console do Google Cloud , acesse a página de gerenciamento de APIs do Agent Registry:

   Acessar a API Agent Registry

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

3. Clique em Desativar API.

4. Na caixa de diálogo de confirmação, clique em Desativar.

gcloud

Desative a API Agent Registry no seu projeto com o comando gcloud services disable:

gcloud services disable agentregistry.googleapis.com \
    --project=PROJECT_ID

Substitua PROJECT_ID pelo ID do projeto.

A seguir

• Aprenda Mais sobre os limites entre projetos
• Guia de início rápido: registrar um agente
• Registrar servidores MCP
• Registrar habilidades
• Pesquisar agentes, ferramentas e habilidades