Configurar recursos da Agent Platform para o Cloud Run

Visualização — Configurar recursos do Agent Platform para o Cloud Run

Este 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 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.

Os recursos da Gemini Enterprise Agent Platform, como identidade do agente e Agent Registry, 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 suas cargas de trabalho de agente.

Este guia mostra como:

• Estabelecer os papéis necessários do IAM
• Entender os tipos funcionais e de identidade
• Configurar recursos para serviços e jobs
• Ver identidades atribuídas
• Ver agentes e ferramentas registrados no Registro de agentes

O Cloud Run é compatível com os seguintes recursos da Agent Platform:

• Identidade do agente: atribui uma identidade exclusiva e criptograficamente verificável à sua 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

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

1. Ative a API Cloud Run Admin, Identity and Access Management, Agent Registry e App Hub, se alguma delas ainda não estiver ativada.

   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 receber essa permissão pelo papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar as APIs

2. Verifique se você configurou o Agent Registry no seu projeto ou organização.
3. Instale e inicialize a CLI gcloud.
4. Atualize os componentes:

   gcloud components update

5. 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 usa contribuem para o custo.

Funções exigidas

Para receber as permissões necessárias para configurar recursos da plataforma do agente, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Para implantar e gerenciar recursos do Cloud Run: Administrador do Cloud Run (roles/run.admin)
• Para gerenciar recursos do App Hub, faça uma destas ações:
  • Administrador do App Hub (roles/apphub.admin)
  • Administrador da API Agent Registry (roles/apiregistry.admin)
• Para fazer a implantação com uma identidade específica, faça uma das seguintes ações:
  • Usuário da conta de serviço do IAM (roles/iam.serviceAccountUser)
  • Administrador da conta de serviço do IAM (roles/iam.serviceAccountAdmin)

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 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 os servidores do 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 definida, essa propriedade não pode ser alterada nem removida. Você atribui à sua 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 definida, essa propriedade não pode ser alterada nem removida. Atribua à sua 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, a Agent Platform ativa os certificados de identidade por padrão. Para desativar, atualize seu 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 agem 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 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 da 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 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 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

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

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

  Importante: ao atualizar um serviço de uma conta de serviço para agent-identity, o Cloud Run atribui um novo principal que não herda permissões da conta de serviço anterior. Para evitar interrupções na conexão, use o Analisador de políticas para identificar e pré-atribuir os papéis necessários ao principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME principal antes de atualizar ou atualize o serviço com --no-traffic para atribuir permissões antes de migrar o tráfego.

  Substitua:

  • SERVICE_NAME: o nome do serviço do Cloud Run.
  • ORGANIZATION_ID: o ID da organização 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 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

Observação:somente os serviços do Cloud Run podem ser expostos como servidores MCP. Os jobs do Cloud Run não podem ser expostos como servidores MCP e só aceitam o tipo funcional agent.

• Para criar um job do 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 seu job do Cloud Run.
  • IMAGE_URL: uma referência à imagem do contêiner.

Ver identidades atribuídas

É possível conferir a identidade do agente atribuído no console Google Cloud 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 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ído.

gcloud

Para conferir a identidade do agente, descreva a revisão do seu 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 é 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 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ído.

gcloud

Para conferir 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 é mostrada 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 ferramentas registrados e saber como armazenar e descobrir agentes e ferramentas com segurança, acesse o Agent Registry.

A seguir

• Saiba como autenticar seus agentes em APIs e ferramentas.
• Saiba como autenticar servidores MCP para conexões seguras.
• Saiba como hospedar servidores MCP no Cloud Run.
• Use o Kit de Desenvolvimento de Agente para criar e registrar agentes personalizados no registro.
• Para criar e implantar agentes que estejam em conformidade com a especificação A2A, consulte Implantar agentes A2A no Cloud Run.
• Consulte o guia de solução de problemas se tiver problemas com o registro de agentes ou a atribuição de identidade.