Usar a identidade do agente com o Agent Runtime

Usar a 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. Este documento explica como criar agentes com identidades de agente, autorizar o acesso às 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 mais seguro do que as contas de serviço. Os controles de gerenciamento de acesso atuais pela identidade do agente de suporte do IAM para permitir uma governança forte.

As credenciais de identidade do agente são protegidas por padrão com uma política de acesso baseado no contexto (CAA, na sigla em inglês) gerenciada pelo Google. Essa política aplica a vinculação 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 base de segurança torna as credenciais roubadas não reproduzíveis, protegendo contra roubo de credenciais e invasão de conta (ATO, na sigla em inglês).

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

Limitações

Não é possível conceder papéis de bucket legado (storage.legacyBucketReader, storage.legacyBucketWriter ou storage.legacyBucketOwner) em buckets do Cloud Storage a identidades de agente.

Criar um agente com identidade de agente

É possível provisionar os 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 tempo de execução do agente e é independente da estrutura do agente usada 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, poderá criar uma identidade de agente sem implantar o código dele. Para isso, crie uma instância do Agent Runtime apenas com o campo identity_type:

    import vertexai
from vertexai import agent_engines
from vertexai import types

client = vertexai.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.agent_engines.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, você pode adicionar o código do agente usando agent_engine.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:

    import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Agent Platform client with v1beta1 API for agent identity support
client = vertexai.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.agent_engines.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
    "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.

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

    agents-cli deploy --agent-identity

  • Implante agentes com a identidade do agente usando a implantação do ADK: configure seu agente com o ADK. Antes de executar adk deploy, execute os comandos a seguir 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 e 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 a API Agent Platform é ativada:

    • 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 imutável do recurso 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 ao modelo, sessões, memórias e sandboxes (pré-lançamento).

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

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

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

Depois de criar um agente com identidade, é possível conceder ou negar o acesso dele a APIs e 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

Conceda permissões do IAM à identidade do agente. Recomendamos as seguintes funções:

  • roles/aiplatform.expressUser: concede acesso à inferência, sessões e memória em execução.

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

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

Outras permissões podem ser necessárias se você usar registro em log, métricas e o registro de APIs do Cloud, além de qualquer outro recurso que você queira expor ao seu agente. Confira mais exemplos depois.

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 compatíveis para o ambiente de execução.

  • AGENT_ENGINE_ID: o ID do recurso da sua 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, as Application Default Credentials do SDK da Agent Platform usam automaticamente a identidade do agente para realizar a autenticação nos recursos doGoogle Cloud .

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 uma função 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, a todos os agentes do 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. Portanto, 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/aiplatform.expressUser

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 uma função 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"

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 do principal.

  • Negue o acesso do agente 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 tempo de execução. Como cada nova implantação cria um recurso reasoningEngines com um ID exclusivo, o agente recebe um novo identificador 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:

  • Recupere o novo ID principal de forma dinâmica: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 necessárias do IAM a essa nova 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 construir dinamicamente a conta principal de identidade do agente com base no ID do recurso google_vertex_ai_reasoning_engine implantado e fazer referência a ela 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 principalSets no escopo do projeto para permissões básicas:como as vinculações principalSet têm como destino todos os agentes em um projeto, elas sobrevivem à exclusão e à recriação do agente. Conceda papéis comuns e não sensíveis (como uso de serviços, geração de registros e inferência de modelo geral) ao principalSet em todo o projeto, em vez de participantes individuais do agente. Limite as vinculações individuais de principal:// a fontes de dados altamente sensíveis.

Registrar a atividade do agente

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 age por conta própria, os registros mostram apenas a identidade dele.

Listar agentes e as identidades deles

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

Console

  1. No Google Cloud console, acesse a página Implantações do Agent Platform.

    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 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 token entre agentes, é possível desativar a política padrão da CAA. Essa ação não é recomendada, já que 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

Aprenda a gerenciar agentes implantados no ambiente de execução gerenciado da Agent Platform.

Guia

Usar um agente com o ambiente de execução da Agent Platform.