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 permitem 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) 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 base de segurança torna as credenciais roubadas não reproduzíveis, protegendo contra roubo de credenciais e invasão de contas (ATO).

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

Limitações

Não é possível conceder às identidades de agente 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 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 ambiente 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 com apenas 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, você pode 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:

    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.

  • 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 seu 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 seu 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 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 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 os seguintes papéis:

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

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

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

Outras permissões podem ser necessárias se você usar registro em log, métricas e registro de API do Cloud, além de qualquer outro recurso que 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 a que 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, o Application Default Credentials do SDK da plataforma do agente usa automaticamente a identidade do agente para realizar a autenticação em recursos doGoogle Cloud .

Conceder acesso para delegação Agent-to-Agent (A2A)

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

Para garantir que a identidade do agente principal 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 principal:

  • Permita que o agente principal pesquise o endpoint do subagente durante a execução: Leitor da API Agent Registry (roles/agentregistry.viewer) no projeto principal ou no recurso de registro
  • Permita que o agente pai envie mensagens para o subagente: Usuário da Agent Platform (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.

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

Por exemplo, para conceder a função 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 principal 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 a 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 pertence 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 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. 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 de 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 novo recurso reasoningEngines com um ID exclusivo, o agente recebe um novo identificador principal. As permissões anteriores 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 de 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 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 construir dinamicamente o principal da identidade do agente com o 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 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 de agentes. 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 principais do agente individual. Limite as vinculações individuais de principal:// a fontes de dados altamente sensíveis.

Registrar atividade do agente

Se você ativar o Cloud Logging, poderá ver registros de qual agente e usuários acessaram um recurso 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 conferir a lista de identidades do agente no Agent Runtime usando o console e a linha de comando do Google Cloud .

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 Filtrar 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 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 tempo de execução do agente:

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.