Usar a identidade do agente com o Vertex AI Agent Engine

Nesta página, descrevemos como usar a identidade do agente do Identity Access Management (IAM) para fornecer recursos de segurança e gerenciamento de acesso ao usar agentes no ambiente de execução do Vertex AI Agent Engine.

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.

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

Limitações

Considere as seguintes limitações ao planejar seu projeto:

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

  • Recomendamos usar a identidade do agente apenas em ambientes de teste.

Criar um agente com identidade

É possível provisionar agentes implantados no Vertex AI Agent Engine com uma identidade exclusiva ao criar a instância do Agent Engine. A identidade está vinculada ao ID do recurso do agente do Vertex AI Agent Engine 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 Engine 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 Engine 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 Engine com a identidade do agente, você pode adicionar o código do agente usando agent_engine.update(...).

  • Criar uma instância do Agent Engine 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 Vertex AI para Python e a flag identity_type=AGENT_IDENTITY:

    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(
      agent=app,
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
          "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
          "staging_bucket": f"gs://"BUCKET _NAME",
      },
)

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

A instância do Agent Engine é 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 Vertex AI:

    • 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 (em inglês). Também fazemos o provisionamento e o gerenciamento automáticos de um certificado x509 no agente com a mesma identidade para autenticação segura.

É possível ver a identidade no console e na API do Vertex AI Agent Engine 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 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 Vertex AI.

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 com o Vertex AI Agent Engine.

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

  • 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 Google Cloud usam automaticamente a identidade do agente para realizar a autenticação nos recursos doGoogle Cloud .

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

Acessar serviços de terceiros usando autoridade delegada com o OAuth

A identidade do agente permite que ele acesse serviços de terceiros em seu nome ao se integrar ao Secret Manager.

Para configurar a integração com o Secret Manager, primeiro armazene as credenciais auxiliares (ID do cliente ou chave secreta do cliente) para acessar os serviços de terceiros no Secret Manager (no projeto consumidor em que o ciclo de vida do agente é gerenciado) seguindo estas etapas:

  1. Crie um contêiner no Secret Manager.

  2. Receba o ID ou a chave secreta do cliente do provedor de apps terceirizado.

  3. Adicione o ID do cliente ou a chave secreta do cliente ao Secret Manager.

  4. Restrinja o acesso a essas credenciais com base no ID do agente (um identificador principal):

    # Create the secret container
gcloud secrets create my-app-oauth-secret

# Add the actual client secret to Secret Manager
gcloud secrets versions add my-app-oauth-secret "gcp-client-secret-1a2b3c4d"

# Grant agent identity access to the secret
gcloud secrets add-iam-policy-binding my-app-oauth-secret \
--role='roles/secretmanager.secretAccessor' \
--member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \

Depois que o segredo é armazenado, o agente pode acessar essas credenciais durante a execução usando o identificador principal e a biblioteca de autenticaçãoGoogle Cloud padrão automaticamente como parte da credencial padrão do aplicativo.

# Example: Use agent identity to retrieve third party credentials from Secret Manager
# Use case: Using an agent, the user is trying to post a message on Slack,
# The developer first retrieves secret from Secret Manager using agent identity,
# and then uses it to login to Slack and post a message.

from google.cloud import secretmanager

def access_secret(project_id: str, secret_id: str, version_id: str = "latest") -> str:

      # Application default credential automatically gets token from MDS using agent identity
      agent_identity_credentials = default()

       # Create the Secret Manager client.
       client = secretmanager.SecretManagerServiceClient(credentials=agent_identity_credentials)

       # Build the resource name of the secret version.
       name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"

       # Access the secret version.
       response = client.access_secret_version(request={"name": name})

       # Decode the payload to get the secret string.
       secret_value = response.payload.data.decode("UTF-8")
       return secret_value

Com o ID e a chave secreta do cliente, agora é possível criar sua ferramenta e configurar a autenticação baseada em OAuth.

O exemplo a seguir usa um agente desenvolvido pelo Kit de Desenvolvimento de Agente (ADK). A autenticação baseada em OAuth é agrupada nos métodos authenticationScheme e authCredential como parte da construção da ferramenta:

import os

from google.adk.auth.auth_schemes import OpenIdConnectWithConfig
from google.adk.auth.auth_credential import AuthCredential, AuthCredentialTypes, OAuth2Auth
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
from google.adk.agents.llm_agent import LlmAgent

auth_scheme = OpenIdConnectWithConfig(
   authorization_endpoint="https://your-endpoint.slack.com/oauth2/v1/authorize",
   token_endpoint="https://your-token-endpoint.slack.com/oauth2/v1/token",
   scopes=['openid', 'profile', "email"]
)

auth_credential = AuthCredential(
 auth_type=AuthCredentialTypes.OPEN_ID_CONNECT,
 oauth2=OAuth2Auth(
   client_id=access_secret(project_id: 'foo', secret_id: 'slack_oauth_client_id'),
   client_secret=access_secret(project_id: 'foo', secret_id: 'slack_oauth_client_secret'),
 )
)

# --- Slack Toolset Configuration Based On OpenAPI Specification ---

with open(os.path.join(os.path.dirname(__file__), 'spec.yaml'), 'r') as f:
   spec_content = f.read()

slack_toolset = OpenAPIToolset(
  spec_str=spec_content,
  spec_str_type='yaml',

  # ** Crucially, associate the authentication scheme and credentials with these tools. **
  # This tells the ADK that the tools require the defined OIDC/OAuth2 flow.
  auth_scheme=auth_scheme,
  auth_credential=auth_credential,
)

# Configure and create the main LLM Agent.

root_agent = LlmAgent(
   model='gemini-2.0-flash',
   name='enterprise_assistant',
   instruction='Help user integrate with Slack and post messages to Slack.',
   tools=userinfo_toolset.get_tools(),
)

Durante a execução, acontece o seguinte (se você usar o ADK localmente pela Web do ADK, as etapas serão automatizadas na Web do ADK e no back-end do ADK):

  1. Você acessa o agente, e ele decide que precisa invocar a ferramenta (por exemplo, o Slack).

  2. As ferramentas programadas no ADK (com auth_scheme e auth_credential) retornam um objeto authConfig para o front-end (que inclui o URI de redirecionamento e o ID do cliente).

  3. O front-end analisa o objeto authConfig, e você é redirecionado para a página de autorização de terceiros. Depois de fazer login, você será redirecionado para o front-end do agente, e o código de autorização será enviado ao back-end do ADK.

  4. O back-end usa o código de autorização para receber um token de acesso para o serviço de terceiros e continua executando a ferramenta.

Se você implantar um agente do ADK no ambiente de execução do Vertex AI Agent Engine, será necessário criar um front-end personalizado e migrar a autenticação da Web do ADK ou redirecionar o código para o front-end e realizar a mesma integração do OAuth.

Acessar serviços de terceiros usando chaves de API

A identidade do agente permite que ele acesse serviços de terceiros e aja em seu nome usando chaves de API. Primeiro, armazene as chaves de API para acesso aos serviços de terceiros no Secret Manager e recupere essas credenciais do Secret Manager.

from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset

WEATHER_DOT_COM_API_KEY = access_secret(project_id: 'foo', secret_id: 'weather_dot_com_api_key')

auth_scheme, auth_credential = token_to_scheme_credential(
   "apikey", "query", "apikey", WEATHER_DOT_COM_API_KEY
)

sample_api_toolset = OpenAPIToolset(
   spec_str="...",
   spec_str_type="yaml",
   auth_scheme=auth_scheme,
   auth_credential=auth_credential,
)

Registrar atividade do agente

Se você ativar o Cloud Logging, poderá ver os 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 de agente no Vertex AI Agent Engine usando o console e a linha de comando Google Cloud .

Console

  1. No console do Google Cloud , acesse a página Vertex AI Agent Engine.

    Acessar o Agent Engine

    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 Engine 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 Engine 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 Engine.

A seguir