Usar a identidade do agente com o Agent Runtime

O uso da identidade do agente no Agent Runtime fornece uma identidade segura por agente que permite uma abordagem de privilégio mínimo para o gerenciamento de acesso. Neste documento, explicamos como criar agentes com identidades de agente, autorizar o acesso a APIs doGoogle Cloud e gerenciar credenciais para serviços de terceiros.

Visão geral

A identidade do agente fornece uma identidade por agente que permite uma abordagem de privilégio mínimo e está vinculada ao ciclo de vida do agente, tornando a identidade do agente um principal de segurança mais seguro do que as contas de serviço. Os controles de gerenciamento de acesso atuais pelo IAM são compatíveis com a identidade do agente para permitir uma governança forte.

As credenciais de identidade do agente são protegidas por padrão por uma política de acesso baseado no contexto (CAA, na sigla em inglês) gerenciada pelo Google. Essa política aplica a vinculação de mTLS para garantir que as credenciais do agente na forma de tokens vinculados a certificados só possam ser usadas no ambiente de execução confiável pretendido (por exemplo, um contêiner do Cloud Run). Essa referência de segurança impede que credenciais roubadas sejam reutilizadas, protegendo contra roubo de credenciais e sequestro de conta (ATO, na sigla em inglês).

Nesta página, abordamos os seguintes tópicos:

• Criar um agente com identidade de agente: crie um agente para que ele receba automaticamente uma identidade exclusiva quando você o implantar no Agent Runtime.

• Autorizar o acesso às APIs do Google Cloud usando a identidade do agente: use a identidade do agente provisionada para conceder ou negar ao agente acesso às ferramentas, APIs e recursos próprios do Google Cloud. Isso também inclui o acesso a outros agentes hospedados no Agent Runtime usando o protocolo Agent2Agent (A2A).

• Registrar atividade do agente do Logging: confira a Identidade do Agente nos registros em todos os serviços do Google Cloud . Para fluxos delegados pelo usuário, os registros mostram a identidade do usuário e do agente.

• Listar agentes e identidade do agente: confira a lista dos seus agentes e as identidades deles no Agent Runtime.

• Desativar o acesso baseado no contexto (não recomendado): desative a política padrão de acesso baseado no contexto (CAA, na sigla em inglês).

Limitações

As identidades de agente não podem receber papéis de bucket legado (storage.legacyBucketReader, storage.legacyBucketWriter ou storage.legacyBucketOwner) em buckets do Cloud Storage.

Criar um agente com identidade de agente

É possível provisionar agentes implantados no Agent Runtime com uma identidade exclusiva ao criar a instância do Agent Runtime. A identidade está vinculada ao ID do recurso do agente do Agent Runtime e é independente do framework usado para desenvolver o agente.

Você tem as seguintes opções ao criar uma identidade de agente:

• Criar uma instância do Agent Runtime sem implantar o código do agente: se você quiser configurar políticas do IAM antes de implantar o agente, crie uma identidade de agente sem implantar o código do agente. Para fazer isso, crie uma instância do Agent Runtime apenas com o campo identity_type:

  import agentplatform
  from agentplatform import types
  
  client = agentplatform.Client(
    project=PROJECT_ID,
    location=LOCATION,
    http_options=dict(api_version="v1beta1")
  )
  remote_app = client.runtimes.create(
    config={
      "display_name": "identity-for-agent",
      "identity_type": types.IdentityType.AGENT_IDENTITY,
    },
  )
  

  Depois de criar a instância do Agent Runtime com a identidade do agente, é possível adicionar o código do agente usando client.runtimes.update(...).

• Criar uma instância do Agent Runtime ao implantar o código do agente: se você quiser provisionar a identidade do agente ao implantar o código dele, use o SDK da Agent Platform para Python e a flag identity_type=AGENT_IDENTITY.

  Defina o agente no framework de sua preferência:

  from google.adk.agents import Agent
  
  agent = Agent(
      model="gemini-2.5-flash",
      name="minimal_agent",
      instruction="You are a helpful assistant.",
  )
  

  Em seguida, implante-o:

  import agentplatform
  from agentplatform import types
  from agentplatform.frameworks import AdkApp
  
  # Initialize the Agent Platform client with v1beta1 API for agent identity support
  client = agentplatform.Client(
    project=PROJECT_ID,
    location=LOCATION,
    http_options=dict(api_version="v1beta1")
  )
  
  # Use the proper wrapper class for your Agent Framework
  app = AdkApp(agent=agent)
  
  # Deploy the agent with Agent Identity
  remote_app = client.runtimes.create(
    agent=app,
    config={
      "display_name": "running-agent-with-identity",
      "identity_type": types.IdentityType.AGENT_IDENTITY,
      "requirements": ["google-cloud-agentplatform[adk,runtimes]"],
      "staging_bucket": f"gs://"BUCKET_NAME",
    },
  )
  
  print(f"Effective Identity: {remote_app.api_resource.spec.effective_identity}")
  

  em que BUCKET_NAME é o nome do bucket do Cloud Storage.

• Implantar agentes usando a Agents CLI: a Agents CLI é ideal para estudantes, prototipagem e testes rápidos, porque oferece uma solução de implantação rápida com recursos básicos de monitoramento. O comando a seguir implanta o agente:

  agents-cli deploy --agent-identity
  

• Implantar agentes com identidade de agente usando a implantação do ADK: configurar seu agente com o ADK. Antes de executar adk deploy, execute os seguintes comandos na pasta do agente para adicionar um arquivo de configuração com a identidade do agente.

  # Create the file
  $ touch .agent_engine_config.json
  
  # Update the file to specify that you're using Agent Identity
  $ echo '{ "identity_type": "AGENT_IDENTITY" }' > .agent_engine_config.json
  

A instância do Agent Runtime é criada com uma identidade de agente somente leitura atestada pelo sistema (um identificador principal):

# Agent identity Format
principal://TRUST_DOMAIN/NAMESPACE/AGENT_NAME

# Example agent identity
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID

As seguintes partes são provisionadas automaticamente para você como parte da identidade do agente:

• TRUST_DOMAIN: um domínio de confiança é provisionado para você quando você ativa a API Agent Platform:

  • Se você tiver uma organização, o domínio de confiança será criado no nível da organização com o formato agents.global.org-ORGANIZATION_ID.system.id.goog.

  • Se o projeto não tiver uma organização, um domínio de confiança será criado no nível do projeto com o formato agents.global.proj-PROJECT_NUMBER.system.id.goog.

• NAMESPACE: o caminho de recurso imutável do agente.

• AGENT_NAME: o agent-reasoning-engine-id imutável.

A identidade do agente é baseada no SPIFFE. Também provisionamos e gerenciamos automaticamente um certificado x509 no agente com a mesma identidade para autenticação segura. Por padrão, o agente tem acesso aos próprios registros, métricas, acesso a modelos, sessões, memórias e sandboxes (pré-lançamento).

As identidades de agente vêm com os papéis padrão roles/aiplatform.agentContextEditor e roles/aiplatform.agentDefaultAccess para que os agentes tenham permissões básicas para operar.

É possível ver a identidade no console e na API do Agent Runtime Google Cloud .

Observação: se a flag de identidade não estiver configurada, a instância do Agent Runtime vai continuar usando contas de serviço. Isso garante a compatibilidade com versões anteriores se você já tiver implementado implantações baseadas em infraestrutura como código nos seus agentes.

Acessar APIs e serviços do Google Cloud usando a identidade do agente

Depois de criar um agente com identidade, é possível conceder ou negar acesso às APIs e aos serviços do Google Cloud usando as seguintes políticas do IAM:

• Políticas de permissão: concedem a um agente acesso a um recurso do Google Cloud .

• Políticas de negação: negam o acesso de um agente a um recurso do Google Cloud .

Conceder acesso a um agente

Conceder permissões do IAM à identidade do agente.

Observação: por padrão, as identidades de agentes implantados recebem os papéis roles/aiplatform.agentDefaultAccess e roles/aiplatform.agentContextEditor, que fornecem todas as permissões necessárias para a operação principal, incluindo a execução de inferência (aiplatform.endpoints.predict), sessões e memória. Não conceda papéis para envolvidos no projeto, como roles/aiplatform.expressUser ou roles/aiplatform.user, a identidades de agentes, porque isso viola o princípio de privilégio mínimo e permite que os agentes modifiquem ou excluam outros agentes no projeto.

Recomendamos os seguintes papéis:

• roles/serviceusage.serviceUsageConsumer: conceda ao agente permissão para usar a cota do projeto e o SDK da plataforma de agentes.

• roles/browser: concede acesso às funcionalidades básicas do Google Cloud .

• roles/secretmanager.secretAccessor: conceder ao agente acesso aos secrets no Secret Manager. Se você referenciar secrets como variáveis de ambiente, também será necessário conceder roles/secretmanager.secretAccessor ao agente de serviço da Agent Platform ([e-mail]) para que ele possa recuperar os valores dos secrets durante a implantação.

Talvez sejam necessárias outras permissões se você usar registros, métricas e o registro da API Cloud, além de qualquer outro recurso que queira expor ao agente. Veja mais exemplos abaixo.

Crie uma política de permissão do IAM para conceder um papel do IAM a um agente:

  # Example: Grant the agent access to vision API.
  gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
  --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \
  --role="ROLE_NAME" \

Substitua:

• RESOURCE_TYPE: o tipo de recurso (por exemplo, projects ou organizations).

• RESOURCE_ID: o ID do recurso ao qual você quer conceder acesso.

• ORGANIZATION_ID: o ID da organização.

• PROJECT_NUMBER: o número do projeto.

• LOCATION: sua região. Consulte as regiões com disponibilidade para o ambiente de execução.

• AGENT_ENGINE_ID: o ID do recurso da instância do Agent Runtime.

• ROLE_NAME é o nome do papel que você quer conceder. Por exemplo, roles/vision.user. Para uma lista de papéis predefinidos, consulte Noções básicas sobre papéis.

Depois que o IAM é configurado, o Application Default Credentials do SDK da plataforma de agentes usa automaticamente a identidade do agente para realizar a autenticação nos recursos doGoogle Cloud .

Conceder acesso para delegação de agente para agente (A2A)

Ao projetar um sistema multiagente em que um agente pai invoca um subagente remoto registrado no Agent Registry, a identidade do agente pai precisa ter permissões para descobrir o subagente no Agent Registry e invocar o endpoint dele.

Para garantir que a identidade do agente pai tenha as permissões necessárias para descobrir e invocar um subagente remoto, peça ao administrador para conceder os seguintes papéis do IAM à identidade do agente pai:

Importante: conceda esses papéis à identidade do agente pai, não à sua conta de usuário. Se os papéis não forem concedidos ao principal correto, poderão ocorrer erros de permissão.

• Permitir que o agente pai procure o endpoint do subagente no ambiente de execução: Leitor da API Agent Registry (roles/agentregistry.viewer) no projeto pai ou no recurso de registro
• Permita que o agente pai envie mensagens ao subagente: Usuário da plataforma de agentes (roles/aiplatform.user) no recurso do mecanismo de raciocínio do subagente de destino

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

O administrador também pode conceder à identidade do agente pai as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Por exemplo, para conceder o papel roles/agentregistry.viewer no projeto, use o seguinte comando da Google Cloud CLI:

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/PARENT_AGENT_ENGINE_ID" \
    --role="roles/agentregistry.viewer"

Substitua:

• ORGANIZATION_ID: o ID da organização.
• PROJECT_NUMBER: o número do projeto.
• LOCATION: a região em que o agente pai está implantado.
• PARENT_AGENT_ENGINE_ID: o ID do recurso da instância do Agent Runtime do agente pai.

Conceder acesso a vários agentes

É possível conceder um papel do IAM a todos os agentes do Agent Runtime em um projeto específico ou em toda uma organização.

Para conceder um papel a todos os agentes do Agent Runtime em um projeto, use um dos comandos a seguir.

Se o projeto pertencer a uma organização:

# Grant all agents in a project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

Se o projeto não pertencer a uma organização:

# Grant all agents in an orgless project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.proj-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

Pode ser mais fácil conceder permissões comuns, como cota, geração de registros ou acesso a modelos para todos os agentes no projeto, para simplificar as implantações. Em seguida, conceda permissões específicas e restritas a agentes individuais para permissões mais sensíveis, como acesso a dados. É possível conceder essas permissões a qualquer momento após o primeiro uso do recurso de identidade do agente em uma organização ou projeto. Assim, isso pode ser feito antes da implantação do agente.

Por exemplo, os comandos a seguir concedem papéis básicos a todos os agentes em um projeto:

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/serviceusage.serviceUsageConsumer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/browser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/cloudapiregistry.viewer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/monitoring.metricWriter

Para conceder um papel a todos os agentes do Agent Runtime em uma organização:

# Grant all agents in an organization the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platform/aiplatform" \
--role="ROLE_NAME"

Conceder acesso para chamadas de agente para agente (A2A)

Se um agente (Agente A) precisar invocar outro agente (Agente B), não conceda permissões para todo o projeto. Em vez disso, conceda um papel personalizado que contenha apenas aiplatform.reasoningEngines.query e aiplatform.reasoningEngines.get, vinculado ao caminho do recurso do Agente B.

1. Crie um papel personalizado agentInvoker com as permissões necessárias:

   gcloud iam roles create agentInvoker --project=PROJECT_ID \
     --permissions=aiplatform.reasoningEngines.query,aiplatform.reasoningEngines.get \
     --stage=GA
   

2. Vincule o papel personalizado ao recurso do Agente B para conceder acesso à identidade do Agente A:

   gcloud beta ai reasoning-engines add-iam-policy-binding AGENT_B_ID \
     --region=LOCATION \
     --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_A_ID" \
     --role="projects/PROJECT_ID/roles/agentInvoker"
   

3. Para impedir que as identidades de agentes realizem operações de gerenciamento sensíveis em outros agentes, crie uma política de negação do IAM para reasoningEngines.create, .delete e .update:

   deniedPrincipals:
     - principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
   deniedPermissions:
     - aiplatform.googleapis.com/reasoningEngines.create
     - aiplatform.googleapis.com/reasoningEngines.delete
     - aiplatform.googleapis.com/reasoningEngines.update
   

Negar acesso a um agente

Para negar o acesso de um agente aos recursos, use a política de negação do IAM ou configure uma política de limite de acesso de principal.

• Negar ao agente o acesso a determinados recursos usando a política de negação do IAM.

  // Deny policy (deny all agents across the org from ability to create or delete buckets)
  
  {
  "displayName": "Deny access to bucket for all agent identities in the org",
  "rules": [
    {
      "denyRule": {
        "deniedPrincipals": [
          "principalSet://<org.id>.global.agent.id.goog/*"
        ],
        "deniedPermissions": [
          "iam.googleapis.com/roles.create",
          "storage.googleapis.com/buckets.delete"
        ]
      }
    }
  ]
  }
  

• Configure o limite de acesso de principal para limitar os recursos que o agente pode acessar, apesar de outras permissões que ele possa ter:

  // PAB Policy (Only allow agents to operate within resource boundary)
  
  {
      "name":"organizations/ORGANIZATION_ID/locations/global/principalAccessBoundaryPolicies/example-policy",
      "details": {
      "rules": [
        {
          "description": "Restrict agent identity inside a folder",
          "resources": [
            "//cloudresourcemanager.googleapis.com/folder/0123456789012"
          ],
          "effect": "ALLOW"
        }
      ],
    }
  }
  
  // Bind PAB policy to all identities in the organization (incl agent id)
  
  gcloud iam principal-access-boundary-policies bindings create example-pab-binding \
        --organization=organizations/ORGANIZATION_ID \
        --policy=example-policy \ --target-principal-set=cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_ID
  

Orientações sobre CI/CD e automação

Pipelines de implantação automatizados que excluem e recriam agentes (como implantações azul-verde, ambientes de teste temporários ou fluxos de trabalho do Terraform) podem sofrer perda silenciosa de acesso ao ambiente de execução. Como cada reimplantação cria um novo recurso reasoningEngines com um ID exclusivo, o agente recebe um novo identificador de principal. As permissões do IAM concedidas ao principal anterior não são herdadas pelo novo principal.

Para gerenciar permissões em pipelines automatizados, use as seguintes estratégias:

• Recuperar o novo ID do principal dinamicamente: capture o valor spec.effectiveIdentity da resposta da implantação ou consulte a API REST após a implantação para receber a identidade ativa do agente. Aplique as vinculações do IAM necessárias a esse novo principal como uma etapa pós-implantação.

  Por exemplo, é possível consultar a identidade ativa com gcloud usando o seguinte comando:

  gcloud ai reasoning-engines describe RESOURCE_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format="value(spec.effectiveIdentity)"
  

  No Terraform, é possível criar dinamicamente o principal de identidade do agente com base no ID do recurso google_vertex_ai_reasoning_engine implantado e fazer referência a ele em vinculações do IAM:

  resource "google_vertex_ai_reasoning_engine" "reasoning_engine" {
    provider = google-beta
  
    project      = var.project_id
    region       = var.region
    display_name = var.display_name
    description  = var.agent_description
  
    spec {
      agent_framework = "google-adk"
      identity_type   = "AGENT_IDENTITY"
  
      source_code_spec {
        inline_source {
          source_archive = filebase64(data.archive_file.agent_tarball.output_path)
        }
  
        python_spec {
          entrypoint_module = var.agent_python_spec.entrypoint_module
          entrypoint_object = var.agent_python_spec.entrypoint_object
          requirements_file = var.agent_python_spec.requirements_path
          version           = var.agent_python_spec.version
        }
      }
  
      deployment_spec {
        env {
          name  = "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY"
          value = "true"
        }
  
        env {
          name  = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
          value = "true"
        }
      }
    }
  }
  
  locals {
    agent_resource_id        = element(split("/", google_vertex_ai_reasoning_engine.reasoning_engine.id), -1)
    agent_identity_principal = "principal://agents.global.org-${data.google_organization.org.org_id}.system.id.goog/resources/aiplatform/projects/${data.google_project.project.number}/locations/${var.region}/reasoningEngines/${local.agent_resource_id}"
  }
  

• Use o principalSets com escopo do projeto para permissões de referência: como as vinculações do principalSet segmentam todos os agentes em um projeto, elas sobrevivem à exclusão e recriação de agentes. Conceda papéis comuns e não confidenciais (como uso de serviço, geração de registros e inferência de modelo geral) ao principalSet em todo o projeto, em vez de principais do agente individuais. Limite as vinculações individuais de principal:// a fontes de dados altamente sensíveis.

Registrar atividade do agente do Logging

Se você ativar o Cloud Logging, poderá ver registros de qual agente e usuários acessaram um recurso do Google Cloud .

• Quando o agente age em nome de um usuário, os registros mostram as identidades do agente e do usuário.

• Quando o agente está agindo por conta própria, os registros mostram apenas a identidade dele.

Listar agentes e as identidades deles

É possível ver a lista de identidades de agente no Agent Runtime usando o console e a linha de comando do Google Cloud .

Console

1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.
   

   Acessar "Implantações"

   Os agentes implantados que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

2. Para cada agente, a identidade é listada na coluna Identidade.

API REST

É possível recuperar a identidade do agente ao receber uma instância do Agent Runtime usando a API REST.

A resposta inclui a identidade do agente no seguinte formato:

{
  ...
  spec: {
    "effectiveIdentity": "agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID"
  }
  ...
}

Para instâncias do Agent Runtime que não usam a identidade do agente, o campo effectiveIdentity contém o nome do agente de serviço ou da conta de serviço associada à instância do Agent Runtime.

Desativar o acesso baseado no contexto (CAA)

Por padrão, tentar usar um token de acesso fora do ambiente de execução pretendido do Agent Runtime resulta no seguinte erro:

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

Para casos extremos, como requisitos específicos de compartilhamento de tokens entre agentes, é possível desativar a política padrão de CAA. Essa ação não é recomendada, porque deixa um agente vulnerável ao roubo de credenciais.

Desative a política padrão de acesso baseado no contexto (CAA) definindo a seguinte variável de ambiente ao criar sua instância do Agent Runtime:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

A seguir

Guia

Gerenciar agentes implantados

Saiba como gerenciar agentes que foram implantados no ambiente de execução gerenciado da Agent Platform.

Guia

Usar um agente

Usar um agente com o ambiente de execução da plataforma de agentes.