Configurar recursos da Agent Platform para o Cloud Run

Os recursos da plataforma de agentes do Gemini Enterprise como a identidade do agente e o registro de agentes oferecem recursos integrados para criar, implantar e gerenciar agentes de IA, servidores do Protocolo de Contexto de Modelo (MCP) e ferramentas. Ao ativar esses recursos para seus recursos do Cloud Run, você pode aproveitar as identidades gerenciadas pelo sistema e o registro automático para simplificar a descoberta e a segurança das cargas de trabalho com agentes.

Este guia aborda como:

O Cloud Run oferece suporte aos seguintes recursos da plataforma de agentes:

  • Identidade do agente: atribui uma identidade exclusiva e criptograficamente verificável à carga de trabalho, permitindo conexões seguras com outros agentes, ferramentas e APIs do Google Cloud.
  • Agent Registry: registra automaticamente seus agentes e ferramentas para que possam ser descobertos por outros desenvolvedores e agentes na sua organização.

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. Instale a Google Cloud CLI.

  4. Configure a CLI gcloud para usar sua identidade federada.

    Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.

  5. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  6. Ative as APIs Cloud Run Admin, Identity and Access Management, Agent Registry e App Hub.

    Funções necessárias para ativar APIs

    Para ativar as APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de proprietário (roles/owner). Caso contrário, você pode receber essa permissão com o papel de administrador do uso de serviços (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar as APIs

  7. Verifique se você configurou o registro de agentes 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 saber mais sobre CPU, memória e saída de rede. O tamanho total do disco provisionado e o tempo de vida da instância que o está usando 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 com papéis personalizados ou outros papéis predefinidos.

Casos de uso

Use os recursos da Agent Platform com o Cloud Run nos seguintes cenários:

  • Autentique seu agente em outros agentes, ferramentas e Google Cloud APIs 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 servidores MCP.

Entender os tipos funcionais e de identidade

Você configura os recursos da Agent Platform definindo propriedades funcionais e de identidade nos recursos do Cloud Run.

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

  • Tipo funcional: declara a finalidade principal da carga de trabalho. Depois de definido, essa propriedade não pode ser alterada ou desmarcada. Você atribui à 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ída à carga de trabalho. Depois de definido, essa propriedade não pode ser alterada ou desmarcada. Você atribui à carga de trabalho um dos seguintes tipos de identidade:
    • agent-identity: atribui uma identidade de agente gerenciada pelo sistema projetada para agentes. Ao implantar com agent-identity, o Agent Platform ativa os certificados de identidade por padrão. Para desativar, atualize o serviço com a --no-identity-certificate flag ou defina a run.googleapis.com/identity-certificate-enabled: "false" anotação. 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 agentes gerenciadas pelo sistema, saiba mais sobre a identidade do agente.
    • service-account: usa uma conta de serviço padrão do Google Cloud.

Comportamento de 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

Você configura os recursos do Agent Platform 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 de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisa 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 sua Google Cloud organização.
    • PROJECT_NUMBER: o número do seu Google Cloud projeto.
    • 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. Opcionalmente, você pode especificar 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 de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisa 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ída à 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 visualizar a identidade do agente atribuída no Google Cloud console ou na CLI gcloud.

Serviços

Console

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

    Acessar o Cloud Run

  2. Selecione Serviços no menu de navegação do Cloud Run e clique no 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 visualizar 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ída é mostrada na saída.

Jobs

Console

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

    Acessar o Cloud Run

  2. Selecione Jobs no menu de navegação do Cloud Run e clique no 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 visualizar 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ída é mostrada na saída.

Ver um agente ou MCP no Agent Registry

Ao implantar 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 visualizar os agentes e ferramentas registrados no registro e aprender a armazenar e descobrir seus agentes e ferramentas com segurança, acesse o registro de agentes.

A seguir