Usar a identidade do agente com o Agent Runtime

Usar a identidade do agente no tempo de execução do agente 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 pelo IAM oferecem suporte à identidade do agente para permitir uma governança forte.

As credenciais de identidade do agente são protegidas por padrão com uma política de acesso sensível ao contexto (CAA) gerenciada pelo Google. Essa política impõe 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:

  • Crie 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, é possível 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 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={"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 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.project-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 fazemos o provisionamento automático e gerenciamos um certificado x509 no agente com a mesma identidade para autenticação segura. Por padrão, o agente tem acesso ao próprio registro, métricas, acesso ao modelo, sessões, memórias e sandboxes (prévia).

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 APIs e serviços usando a identidade do agente Google Cloud

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 plataforma de agentes.

  • 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 da API do Cloud, além de qualquer outro recurso que queira expor ao seu agente. Consulte 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:

  • 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 ambiente de execução do agente.

  • 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 do 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 ambiente de execução do agente 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.project-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 principal para restringir 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

Registrar atividade do agente

Se você ativar o Cloud Logging, poderá ver registros de qual agente e quais 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 do agente no Agent Runtime usando o console e a linha de comando do Google Cloud .

Console

  1. No console Google Cloud , 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 tempo de execução do agente 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 ambiente de execução do agente 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 ambiente de execução do agente.

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 tokens entre agentes, é possível desativar a política padrão da CAA. Essa ação é altamente desencorajada, 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

Use um agente com o ambiente de execução do Agent Platform.