Usar a identidade do agente com o Agent Runtime

O uso da identidade do agente no Agent Runtime oferece 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 a Google Cloud APIs 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 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 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 linha de base de segurança torna as credenciais roubadas não reproduzíveis, protegendo contra roubo de credenciais e sequestro de contas (ATO, na sigla em inglês).

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

Limitações

As identidades de agente não podem receber papéis de bucket legados (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 da estrutura de 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, 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 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 código de 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 do agente, use o SDK da plataforma de agentes para Python e a identity_type=AGENT_IDENTITY flag.

    Defina o agente na estrutura 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 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.

  • Implantar agentes usando a CLI de agentes: A CLI de agentes é ideal para aprendizado, prototipagem e testes rápidos, porque 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

  • Implantar agentes com a identidade do agente usando a implantação do ADK: Configure o 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 partes a seguir são provisionadas automaticamente como parte da identidade do agente:

  • TRUST_DOMAIN: um domínio confiável é provisionado quando você ativa a API Agent Platform:

    • Se você tiver uma organização, o domínio confiável 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 confiável será criado no nível do projeto com o formato agents.global.project-PROJECT_NUMBER.system.id.goog.

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

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

A identidade do agente é baseada em 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 (visualização).

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

É possível visualizar a identidade pelo console e pela 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 de agente, é possível conceder ou negar o acesso do agente a Google Cloud APIs e serviços usando as seguintes políticas do IAM:

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

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

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ência, sessões e memória.

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

  • roles/browser: conceda acesso a funcionalidades básicas. Google Cloud

Permissões adicionais podem ser necessárias se você usar registros, métricas e o registro da API Cloud, e para qualquer outro recurso que você queira expor ao 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 sua organização.

  • PROJECT_NUMBER: o número do seu projeto.

  • LOCATION: sua região. Consulte as regiões com suporte 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, as credenciais padrão do aplicativo do SDK da plataforma de agentes usam automaticamente a identidade do agente para realizar a autenticação nos recursos.Google 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 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 pertence 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, elas podem ser realizadas 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 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"

Negar acesso a um agente

Para negar o acesso de um agente a recursos, use a política de negação do IAM ou configure uma política de limite de acesso 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 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

Registrar a atividade do agente

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

  • 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 do agente.

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

    Acessar "Implantações"

    Os agentes implantados que fazem parte do projeto selecionado aparecem na lista. É possível usar o campo Filtrar para filtrar a lista pela coluna especificada.

  2. Para cada agente, a identidade do agente é 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 tokens entre agentes, é possível desativar a política de CAA padrão. Essa ação não é recomendada, porque deixa um agente vulnerável ao roubo de credenciais.

Desative a política de Acesso Baseado no Contexto (CAA) padrão definindo a seguinte variável de ambiente ao criar a 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 que foram implantados no ambiente de execução gerenciado da plataforma de agentes.

Guia

Use um agente com o Agent Platform Runtime.