Configurar recursos da Agent Platform para o Cloud Run

A Gemini Enterprise Agent Platform oferece recursos integrados para criar, implantar e gerenciar agentes de IA, servidores do Protocolo de Contexto de Modelo (MCP) e ferramentas. Isso permite que você aproveite as identidades gerenciadas pelo sistema e o registro automático para simplificar a descoberta e a segurança das suas cargas de trabalho agênticas.

  • A identidade do agente atribui uma identidade criptográfica exclusiva à carga de trabalho do Cloud Run para que ela possa se conectar a outros agentes, ferramentas e APIs do Google Cloud .
  • O Agent Registry registra seus agentes e ferramentas para que desenvolvedores e agentes em toda a organização possam descobri-los.

Este guia mostra como:

Antes de começar

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Install the Google Cloud CLI.

  4. Configure the gcloud CLI to use your federated identity.

    For more information, see Sign in to the gcloud CLI with your federated identity.

  5. To initialize the gcloud CLI, run the following command: 

    gcloud init

  6. Ative a API Cloud Run Admin, Identity and Access Management, Agent Registry e App Hub, se ainda não estiverem ativadas.

    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 as APIs

  7. Verifique se você configurou o Agent Registry no seu projeto ou organização.
  8. Instale e inicialize a CLI gcloud.
  9. Atualize os componentes: 
    gcloud components update
  10. Consulte a página de preços do Cloud Run para CPU, memória e saída de rede. O tamanho total do disco provisionado e o ciclo de vida da instância que o utiliza contribuem para o custo.

Funções exigidas

Para receber as permissões necessárias para configurar os recursos da Plataforma de Agentes, 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 usando papéis personalizados ou outros papéis predefinidos.

Casos de uso

Use os recursos da plataforma de agentes com o Cloud Run nos seguintes cenários:

  • Autentique seu agente para outros agentes, ferramentas e APIs do Google Cloud usando uma identidade exclusiva gerenciada pelo sistema e vinculada ao ciclo de vida dele.
  • Ative a descoberta automática de agentes e servidores MCP no Agent Registry da sua organização.
  • Use o Identity-Aware Proxy como uma política de autenticação para proteger os servidores MCP.

Entender os tipos funcionais e de identidade

Para configurar os recursos da Agent Platform, defina propriedades funcionais e de identidade nos recursos do Cloud Run.

Estas duas propriedades controlam como registrar e identificar uma carga de trabalho:

  • Tipo funcional: declara o objetivo principal da carga de trabalho. Depois de definida, essa propriedade não pode ser alterada ou removida. Atribua à carga de trabalho um dos seguintes tipos funcionais:
    • agent: designa a carga de trabalho como um agente de IA. As cargas de trabalho desse tipo precisam usar o tipo agent-identity.
    • mcp-server: designa a carga de trabalho como um servidor MCP gerenciado pelo usuário. Esse tipo pode usar qualquer tipo de identidade compatível.
  • Tipo de identidade: especifica o tipo de identidade atribuído à carga de trabalho. Depois de definida, essa propriedade não pode ser alterada ou removida. Atribua à carga de trabalho um dos seguintes tipos de identidade:
    • agent-identity: atribui uma identidade de agente gerenciada pelo sistema projetada para agentes. Quando você implanta com agent-identity, a Agent Platform ativa os certificados de identidade por padrão. Para desativar, atualize o serviço com a flag --no-identity-certificate ou defina a anotação run.googleapis.com/identity-certificate-enabled: "false". Siga o guia para autenticar ferramentas e recursos para agentes que atuam por conta própria ou em nome de usuários finais. Para entender os conceitos básicos e os benefícios de segurança das identidades de agente gerenciadas pelo sistema, saiba mais sobre a identidade do agente.
    • service-account: usa uma conta de serviço padrão do Google Cloud.

Comportamento da configuração

O comportamento das propriedades funcionais e de identidade depende da combinação escolhida:

Tipo funcional Tipo de identidade Comportamento resultante
agent agent-identity A carga de trabalho é registrada como um agente no Agent Registry e recebe uma identidade de agente gerenciada pelo sistema.
agent Outro ou não especificado Erro. As cargas de trabalho com functional-type=agent precisam usar identity-type=agent-identity.
mcp-server agent-identity, service-account ou não especificado A carga de trabalho é registrada como um servidor MCP (/mcpServers) no Agent Registry. Se não for especificado, o padrão será uma identidade de conta de serviço.
Não especificado service-account A carga de trabalho é executada como um serviço ou job padrão do Cloud Run.

Configurar recursos em serviços e jobs

Configure os recursos da Plataforma de Agentes nos serviços e jobs do Cloud Run usando a Google Cloud CLI.

Serviços

  • Para implantar um agente, especifique --functional-type=agent e --identity-type=agent-identity:

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=agent \
    --identity-type=agent-identity

    Substitua:

    • SERVICE_NAME: o nome do serviço do Cloud Run.
    • IMAGE_URL: uma referência à imagem do contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

  • Para atualizar um serviço atual para usar a identidade do agente:

    gcloud beta run services update SERVICE_NAME \
    --functional-type=agent \
    --identity-type=agent-identity \
    --no-traffic

    Substitua:

    • SERVICE_NAME: o nome do serviço do Cloud Run.
    • ORGANIZATION_ID: o ID da organização do Google Cloud.
    • PROJECT_NUMBER: o número do projeto do Google Cloud .
    • REGION: a região em que o serviço está implantado.

  • Para implantar um servidor MCP gerenciado pelo usuário, especifique --functional-type=mcp-server. Se quiser, especifique um tipo de identidade usando --identity-type:

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=mcp-server \
    --identity-type=IDENTITY_TYPE

    Substitua:

    • SERVICE_NAME: o nome do serviço do Cloud Run.
    • IMAGE_URL: uma referência à imagem do contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • IDENTITY_TYPE: opcional. O tipo de identidade atribuído à carga de trabalho. Especifique agent-identity ou service-account. O padrão é service-account.

Jobs

  • Para criar um job de agente, especifique --functional-type=agent e --identity-type=agent-identity:

    gcloud beta run jobs create JOB_NAME \
  --image=IMAGE_URL \
  --functional-type=agent \
  --identity-type=agent-identity

    Substitua:

    • JOB_NAME: o nome do job do Cloud Run.
    • IMAGE_URL: uma referência à imagem do contêiner.

Ver identidades atribuídas

É possível ver a identidade do agente atribuída no console do Google Cloud ou na CLI gcloud.

Serviços

Console

  1. No console do Google Cloud , acesse o Cloud Run:

    Acessar o Cloud Run

  2. Selecione Serviços no menu de navegação do Cloud Run e clique no seu serviço.

  3. Clique na guia Revisões e selecione uma revisão.

  4. Clique na guia Segurança.

O campo Identidade mostra a identidade do agente atribuída.

gcloud

Para ver a identidade do agente, descreva a revisão do serviço:

gcloud beta run revisions describe REVISION_NAME

Substitua REVISION_NAME pelo nome da revisão do serviço.

A identidade do agente atribuído é exibida na saída.

Jobs

Console

  1. No console do Google Cloud , acesse o Cloud Run:

    Acessar o Cloud Run

  2. Selecione Jobs no menu de navegação do Cloud Run e clique no seu job.

  3. Clique na guia Execuções e selecione uma execução.

  4. Confira os detalhes da execução.

O campo Identidade mostra a identidade do agente atribuída.

gcloud

Para ver a identidade do agente de uma execução de job, descreva a execução:

gcloud beta run jobs executions describe EXECUTION_NAME

Substitua EXECUTION_NAME pelo nome da execução do job.

A identidade do agente atribuído é exibida na saída.

Ver um agente ou MCP no Agent Registry

Quando você implanta um recurso do Cloud Run com --functional-type=agent ou --functional-type=mcp-server, ele é registrado automaticamente no Agent Registry da sua organização.

  • Os agentes são registrados no catálogo de agentes (/agents).
  • Os servidores MCP são registrados no catálogo de servidores MCP (/mcpServers).

Para conferir os agentes e as ferramentas registrados no registro e saber como armazenar e descobrir seus agentes e ferramentas com segurança, acesse o Agent Registry.

A seguir