Limites entre projetos

Os limites de gerenciamento entre projetos (ou limites) permitem descobrir, gerenciar e governar agentes de IA, servidores do Protocolo de Contexto de Modelo (MCP, na sigla em inglês) e ferramentas em vários projetos do Google Cloud . O Agent Registry opera em um único projeto de governança por padrão, mas a configuração de um limite de gerenciamento no Resource Manager permite que um projeto de gerenciamento central agregue agentes, servidores MCP e ferramentas em projetos de membros distribuídos. Entender como os limites de gerenciamento estruturam os papéis do projeto, a agregação de recursos e o controle de acesso ajuda a projetar topologias de vários projetos escalonáveis.

Para configurar um limite de gerenciamento, consulte Configurar um limite de gerenciamento para vários projetos.

Modelo de limite

Defina um limite de gerenciamento em uma pasta ou organização no Resource Manager:

  • Limite para toda a pasta ou organização: por padrão, se você criar um limite em uma pasta ou organização sem configurar um filtro de tag, o limite incluirá todos os projetos filhos nessa pasta ou organização como projetos membros.
  • Limites filtrados por tag (opcional): para particionar projetos filhos em uma pasta ou organização em vários limites, é possível filtrar a associação de limites usando tags do Resource Manager. Por exemplo, é possível separar os ambientes prod e dev. Anexe tags aos Google Cloud projetos que você quer incluir em cada limite. Quando um projeto filho na pasta ou organização tem uma tag que corresponde ao filtro de limite, esse projeto se torna um projeto membro do limite de gerenciamento.

Ao usar tags para particionar limites de gerenciamento, elas oferecem os seguintes benefícios:

  • Inscrição dinâmica e automatizada: os ambientes de nuvem modificam projetos com frequência. Quando você marca um projeto com um valor de tag inscrito, como env=prod, o Agent Registry o inclui automaticamente como um projeto membro no limite, sem exigir atualizações manuais nas definições de limite.
  • Desacoplamento de hierarquias de pastas: as estruturas de pastas do Resource Manager geralmente são organizadas para fins de faturamento ou de negócios. As tags separam as definições de limite das hierarquias de pastas físicas, permitindo que você estabeleça perímetros de gerenciamento entre pastas em uma pasta ou organização pai.
  • Herança e escalonabilidade: as tags aplicadas a uma organização ou pasta são propagadas automaticamente pela hierarquia de recursos para pastas e projetos filhos. Esse modelo de herança permite que você registre ramificações inteiras da árvore de recursos com uma única atribuição de tag.
  • Governança centralizada: as tags são regidas por permissões centralizadas do Identity and Access Management (IAM). Ao usar tags para definir limites de gerenciamento, é possível impedir que usuários individuais adicionem ou removam projetos do limite de forma arbitrária.

Arquitetura e recursos principais

Um limite de gerenciamento entre projetos depende dos seguintes recursos do Resource Manager:

  • Configuração de limite (recurso BoundaryConfig): um recurso de configuração em uma organização ou pasta no Resource Manager que estabelece as regras de particionamento de limite nessa pasta ou organização. Se você não definir uma chave de tag no recurso BoundaryConfig, a organização ou pasta vai aceitar um único limite que inclui todos os projetos filhos. Para particionar projetos filhos em vários limites filtrados por tag, o recurso BoundaryConfig especifica a chave de tag de recurso único, como 123456789012/env, usada para avaliar a associação do projeto nessa pasta ou organização.

  • Limite (recurso Boundary): um perímetro de projetos membros em uma organização ou pasta. Sem um filtro de tag, o limite inclui todos os projetos filhos na organização ou pasta pai. Ao configurar uma chave de tag no recurso pai BoundaryConfig, o recurso Boundary especifica um filtro de valor de tag, como env=prod, e os projetos filhos que herdam ou anexam esse valor de tag pertencem ao limite automaticamente. Como o recurso BoundaryConfig de um pai usa uma única chave de tag e um projeto pode ter apenas um valor de tag efetivo por chave de tag, um projeto pode pertencer a no máximo um limite por pasta ou organização pai.

  • Configuração de recurso (recurso CapabilityConfig): um recurso definido em uma organização, pasta ou projeto. No nível da organização ou da pasta, ela vincula um ou mais limites a um projeto de gerenciamento dedicado e especifica os recursos de gerenciamento ativados nesses limites. No nível do projeto, ele permite recursos de gerenciamento para um único projeto independente sem limites. Para o Agent Registry, configure o recurso AGENT_MANAGEMENT (Google Cloud CLI: agent-management), que permite a descoberta centralizada de componentes, resumos de pesquisa e governança entre projetos no Agent Registry, além de ativar automaticamente o agentregistry.googleapis.com no projeto de gerenciamento.

Para mais informações sobre esses recursos do Resource Manager, consulte Visão geral dos limites e recursos de gerenciamento.

O diagrama a seguir ilustra como os recursos do Resource Manager conectam projetos de membros a um projeto de gerenciamento central:

Diagrama que ilustra como os recursos do Cloud Resource Manager vinculam projetos membros a um projeto de gerenciamento central.
Figura 1. Arquitetura de um limite de gerenciamento entre projetos que conecta projetos de membros a um projeto de gerenciamento central.

Gerenciamento de vários projetos

Um limite de gerenciamento separa a governança administrativa da execução de computação em dois papéis de projeto distintos: um projeto de gerenciamento central e um ou mais projetos de membro.

Essa estrutura desacoplada impõe o isolamento de vários locatários. As equipes criam e implantam agentes nos respectivos projetos de membros sem precisar de acesso direto a outros projetos de membros, e os administradores e orquestradores mantêm uma visibilidade unificada em todo o limite de gerenciamento do projeto de gerenciamento.

Projeto de gerenciamento

Um projeto de gerenciamento é um projeto do Google Cloud que serve como o projeto de governança central para um limite de gerenciamento. Ele centraliza a configuração da API, o controle de acesso, o faturamento, o consumo de cotas e os metadados de componentes agregados no limite sem precisar hospedar ambientes de execução de computação subjacentes.

No Agent Registry, o projeto de gerenciamento executa as seguintes funções:

  • Vinculação de limite e capacidade: associa-se a um ou mais limites no Resource Manager por meio de um recurso CapabilityConfig com a capacidade AGENT_MANAGEMENT ativada. Para ver as etapas de configuração, consulte Configurar limites de gerenciamento.
  • Descoberta e pesquisa centralizadas: serve como o projeto de destino para solicitações de lista e pesquisa entre projetos, permitindo que orquestradores, desenvolvedores e aplicativos cliente interajam com agentes, servidores MCP e ferramentas descobertos automaticamente em todos os projetos membros no limite.
  • Registro de recursos em todo o limite: hospeda recursos Service registrados manualmente, como agentes personalizados, servidores MCP externos e endpoints, e recursos Binding quando você quer que eles fiquem visíveis em todo o limite de gerenciamento.
  • Gerenciamento centralizado de APIs, faturamento e cotas: consolida a ativação da API Agent Registry, a alocação de cotas e o faturamento para operações de descoberta e governança no nível do limite.

Ao configurar um recurso CapabilityConfig em uma pasta ou organização no Resource Manager, é possível provisionar o projeto de gerenciamento de uma das seguintes maneiras:

  • Projeto de gerenciamento autogerenciado: você designa um projeto doGoogle Cloud que você gerencia transmitindo a flag --management-project ao criar o recurso CapabilityConfig. O projeto precisa residir diretamente na mesma pasta ou organização pai que o recurso CapabilityConfig e não pode servir como um projeto de gerenciamento para outro recurso CapabilityConfig. Se você excluir o recurso CapabilityConfig posteriormente, o Resource Manager vai preservar o projeto autogerenciado e revertê-lo para um projeto padrão.
  • Projeto de gerenciamento gerenciado pelo Google: omita a flag --management-project ao criar o recurso CapabilityConfig, e o Resource Manager vai criar e gerenciar automaticamente um novo projeto para você na pasta ou organização pai. O projeto gerado tem um prefixo de ID do projeto de google-mpf ou google-mpo. Se você excluir o recurso CapabilityConfig posteriormente, o Resource Manager vai excluir esse projeto gerenciado pelo Google.

Em ambos os casos, a criação do recurso CapabilityConfig com agent-management ativa automaticamente agentregistry.googleapis.com no projeto de gerenciamento.

Projetos de membros

Os projetos de membro são os projetos do Google Cloud que pertencem a um limite de gerenciamento. Eles podem ser todos os projetos filhos na pasta ou organização pai do limite ou os projetos filhos que correspondem a um filtro de tag de limite opcional, como env=prod. Os agentes, servidores MCP e ferramentas descobertos automaticamente são executados em projetos membros.

Os projetos membros mantêm os próprios recursos de computação locais, como mecanismos de raciocínio do Agent Runtime, serviços do Cloud Run ou clusters do GKE. Os recursos descobertos automaticamente são ingeridos localmente em cada projeto membro e agregados ao projeto de gerenciamento quando você lista ou pesquisa o registro. Por outro lado, os recursos registrados manualmente que você cria em um projeto membro só ficam visíveis quando você envia uma solicitação para esse projeto membro individual.

A associação de projetos de membros a um projeto de gerenciamento em um limite está sujeita aos limites do sistema. Exceder esse limite pode causar erros de rollup. Para mais informações, consulte Cotas e limites do sistema.

Registro e rollup

A descoberta entre projetos no Registro de Agentes distingue entre recursos descobertos automaticamente implantados em projetos membros e recursos registrados manualmente com escopo no projeto em que são criados.

Recursos descobertos e registrados automaticamente

O escopo de um recurso em um limite de gerenciamento depende de como ele é registrado:

  • Agentes e servidores MCP descobertos automaticamente: os recursos compatíveis implantados em projetos membros, como mecanismos de raciocínio do Agent Runtime, serviços do Cloud Run e implantações do GKE, são ingeridos automaticamente no projeto membro em que são implantados e agregados ao projeto de gerenciamento.

  • Recursos e vinculações registrados manualmente: os recursos do Service registrados manualmente, como agentes personalizados, servidores MCP externos, endpoints e recursos do Binding, têm como escopo o projeto em que são criados:

    • Crie-os no projeto de gerenciamento se quiser que eles fiquem visíveis no limite de gerenciamento.
    • Crie-os em um projeto de membro se quiser que eles fiquem visíveis apenas nesse projeto.

  • Habilidades, editores e aplicativos de IA independentes: os recursos personalizados independentes Skill, SkillRevision, Publisher e AiApplication têm como escopo o projeto em que são criados e não são agregados entre os projetos membros em um limite de gerenciamento. Registre habilidades independentes personalizadas e aplicativos de IA no projeto em que seus agentes ou desenvolvedores precisam descobri-los. As habilidades independentes gerenciadas pelo Google podem ser descobertas automaticamente em qualquer projeto.

Agregação de consultas centralizada

A forma como o Registro de Agentes define o escopo dos locais depende de você consultar um projeto de governança independente, um projeto membro ou um projeto de gerenciamento em um limite de gerenciamento:

  • Projetos de governança independentes e projetos de membros: as consultas em um local compatível com o Agent Registry, como us-central1, europe-west1, us, eu ou global, retornam apenas recursos nesse local para esse único projeto, sem rollup entre projetos.

  • Projeto de gerenciamento: quando você ativa um recurso CapabilityConfig com agent-management em um projeto de gerenciamento, o rollup entre projetos é compatível com todos os locais compatíveis com o Agent Registry. Consultar um local no projeto de gerenciamento agrega recursos no mesmo local em todo o projeto de gerenciamento e em todos os projetos membros no limite de gerenciamento. Esse resumo não inclui recursos em locais diferentes:

    • Regiões únicas: as consultas em uma única região, como us-central1 ou europe-west1, agregam agentes descobertos automaticamente e servidores MCP implantados nessa região no projeto de gerenciamento e nos projetos membros, além dos recursos Service e Binding criados nessa região no projeto de gerenciamento.
    • Multirregiões: as consultas em uma multirregião, como us ou eu, agregam agentes descobertos automaticamente e servidores MCP implantados nessa multirregião no projeto de gerenciamento e nos projetos membros. As consultas em multirregiões não agregam recursos implantados em regiões únicas.
    • Global: as consultas no local global agregam agentes descobertos automaticamente e servidores MCP implantados em global no projeto de gerenciamento e nos projetos membros, além dos recursos Service e Binding criados em global no projeto de gerenciamento. As consultas em global não agregam recursos implantados em multirregiões ou regiões únicas.

Quando você lista, pesquisa ou recupera componentes de agentes em um local no projeto de gerenciamento, o Agent Registry executa as seguintes etapas:

  1. Identifica todos os projetos de membros associados ao projeto de gerenciamento pelo recurso CapabilityConfig ativo.
  2. Consulta agentes e servidores MCP descobertos automaticamente nesse local no projeto de gerenciamento e em cada projeto membro, além de todos os recursos Service registrados manualmente criados nesse local no projeto de gerenciamento.
  3. Agrega recursos correspondentes em um conjunto de resultados unificado.
  4. Retorna os resultados agregados para você.

Se vários limites forem anexados ao mesmo recurso CapabilityConfig, o Agent Registry vai agregar os projetos de membros de todos os limites anexados no mesmo registro de projeto de gerenciamento. Para restringir a lista ou os resultados da pesquisa no projeto de gerenciamento a um único projeto de membro, transmita --filter="project_id=MEMBER_PROJECT_ID". Se dois ambientes exigirem visibilidade separada, crie um recurso CapabilityConfig e um projeto de gerenciamento separados para cada limite.

A descoberta de projeto único e entre projetos usam métodos de API idênticos. O escopo da pesquisa depende se o projeto de destino é um projeto de membro ou de gerenciamento.

Nomes de recursos em um limite de gerenciamento

Quando um componente é incluído em um projeto membro, o Agent Registry atribui a ele um ID, como AGENT_ID ou SERVER_ID. Quando você lista, pesquisa ou recebe um componente em um limite de gerenciamento, o Agent Registry preserva o ID desse componente e formata o nome do recurso associado com base no projeto que você usa:

  • Projeto de gerenciamento: quando você lista, pesquisa ou recebe componentes usando o projeto de gerenciamento, cada nome de recurso usa o projeto de gerenciamento.
  • Projeto de membro: quando você lista, pesquisa ou recebe componentes usando o projeto de membro em que o recurso está implantado, cada nome de recurso usa esse projeto de membro.

A tabela a seguir mostra o URL da solicitação e o nome do recurso associado para recursos descobertos automaticamente implantados em um projeto membro:

Tipo de recurso URL de solicitação Nome do recurso associado
Agente projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/agents/AGENT_ID projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/agents/AGENT_ID
projects/MEMBER_PROJECT_ID/locations/LOCATION/agents/AGENT_ID projects/MEMBER_PROJECT_ID/locations/LOCATION/agents/AGENT_ID
Servidor MCP projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID
projects/MEMBER_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID projects/MEMBER_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID

O nome do recurso associado reflete o projeto na sua solicitação. No entanto, o identificador de registro e a referência de ambiente de execução do componente permanecem imutáveis e sempre retêm o projeto membro em que a carga de trabalho subjacente é executada.

Visualização de topologia e fluxos de tráfego

Os administradores de plataforma e os arquitetos de IA podem visualizar as relações entre vários agentes e o tráfego entre projetos usando o gráfico de topologia.

O gráfico de topologia mostra as seguintes dimensões arquitetônicas:

  • Correlação de referência de ambiente de execução: correlaciona o identificador de agente lógico com a referência de ambiente de execução física. Essa correlação permite que os operadores rastreiem um agente no Agent Registry diretamente para o mecanismo de raciocínio do Agent Runtime, o serviço do Cloud Run ou a implantação do GKE subjacentes.
  • Vinculações entre projetos: mostra vinculações entre agentes de orquestração em um projeto e servidores MCP ou ferramentas downstream em outro projeto.
  • Verificação de perímetro: ajuda os administradores a verificar se a comunicação do agente obedece aos perímetros do VPC Service Controls e é roteada por endpoints designados do Gateway de Agente.

Controle de acesso

Em um limite de gerenciamento, você concede papéis de descoberta do IAM no projeto de gerenciamento para que os usuários e orquestradores possam pesquisar no limite sem precisar de acesso direto do IAM a projetos de membros individuais. Como os recursos Service e Binding registrados manualmente criados em um projeto membro não são transferidos para o projeto de gerenciamento, os administradores de segurança também podem restringir a criação local de Service e Binding em projetos membros usando uma restrição de política da organização ou uma política de negação do IAM. Quando os agentes em projetos membros invocam ferramentas ou se comunicam com agentes em outros projetos além do limite, o tráfego pode ser roteado por um Gateway de Agente central.

Para recursos em um limite de gerenciamento, as restrições do VPC Service Controls se aplicam apenas às interações do Agent Registry no projeto de gerenciamento. O Agent Registry pode descobrir agentes e servidores MCP em todos os projetos membros no limite de gerenciamento, mesmo que esses projetos não estejam no mesmo perímetro de serviço que o projeto de gerenciamento.

Para mais informações sobre os papéis necessários para a configuração de limites, o acesso ao registro e as restrições de gravação de projetos de membros, consulte Papéis para limites de gerenciamento entre projetos.

A seguir