Use a identidade do agente com o Vertex AI Agent Engine

Esta página descreve como usar a identidade do agente da gestão de identidade e acesso (IAM) para fornecer funcionalidades de segurança e gestão de acesso quando usar agentes no tempo de execução do Vertex AI Agent Engine.

Vista geral

A identidade do agente fornece uma identidade por agente que permite uma abordagem de privilégios mínimos e está associada ao ciclo de vida do agente, o que torna a identidade do agente um principal mais seguro do que as contas de serviço. Os controlos de gestão de acesso existentes através da IAM suportam a identidade do agente para permitir uma governação forte.

Esta página aborda os seguintes tópicos:

Limitações

Considere as seguintes limitações quando planear o seu projeto:

  • Não é possível conceder identidades de agentes a funções de contentores antigos (storage.legacyBucketReader, storage.legacyBucketWriter ou storage.legacyBucketOwner) em contentores do Cloud Storage.

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

Crie um agente com identidade do agente

Pode aprovisionar agentes que implementa no Vertex AI Agent Engine com uma identidade única quando cria a instância do Agent Engine. A identidade está associada ao ID do recurso do agente do Vertex AI Agent Engine e é independente da framework de agentes que usou para desenvolver o agente.

Tem as seguintes opções quando cria uma identidade de agente:

  • Crie uma instância do Agent Engine sem implementar código do agente: se quiser configurar políticas de IAM antes de implementar o agente, pode criar uma identidade do agente sem implementar o código do agente. Para tal, crie uma instância do Agent Engine 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 Engine com a identidade do agente, pode adicionar código do agente através de agent_engine.update(...).

  • Crie uma instância do Agent Engine durante a implementação do código do agente: se quiser aprovisionar a identidade do agente durante a implementação do código do agente, use o SDK do 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 seu contentor do Cloud Storage.

A instância do Agent Engine é criada com uma identidade do agente atestada pelo sistema e só de leitura (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 aprovisionadas automaticamente para si como parte da identidade do agente:

  • TRUST_DOMAIN: é aprovisionado um domínio fidedigno para si quando ativa a API Vertex AI:

    • Se tiver uma organização, o domínio de confiança é criado ao nível da organização com o formato agents.global.org-ORGANIZATION_ID.system.id.goog.

    • Se o seu projeto não tiver uma organização, é criado um domínio fidedigno ao 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 baseia-se no SPIFFE. Também aprovisionamos e gerimos automaticamente um certificado x509 no agente com a mesma identidade para autenticação segura.

Pode ver a identidade através da consola e da API do Vertex AI Agent Engine Google Cloud .

Aceda a Google Cloud APIs e serviços através da identidade do agente

Depois de criar um agente com identidade do agente, pode conceder ou recusar o acesso do agente a Google Cloud APIs e serviços através das seguintes políticas de IAM:

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

  • Políticas de recusa: recusam o acesso de um agente a um Google Cloud recurso.

Conceda acesso a um agente

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

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

  • roles/serviceusage.serviceUsageConsumer: conceda ao agente autorização para usar a quota do projeto e o SDK Vertex AI.

Crie uma política de autorização de IAM para conceder uma função de 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 o seguinte:

  • ORGANIZATION_ID: o ID da sua organização.

  • PROJECT_NUMBER: o número do seu projeto.

  • LOCATION: a sua região. Consulte as regiões suportadas para o Vertex AI Agent Engine.

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

  • ROLE_NAME é o nome da função que quer conceder. Por exemplo, roles/vision.user. Para ver uma lista de funções predefinidas, consulte o artigo Compreender as funções.

Depois de o IAM ser configurado, as Credenciais padrão da aplicação do SDK Google Cloud usam automaticamente a identidade do agente para realizar a autenticação nosGoogle Cloud recursos.

Negue o acesso a um agente

Para negar o acesso de um agente aos recursos, pode usar a política de negação do IAM ou configurar uma política de limite de acesso principal.

  • Negar o acesso do agente a determinados recursos através da política de negação da 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 aos quais o agente pode aceder, apesar de outras autorizações que o agente 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

Aceda a serviços de terceiros através de autoridade delegada com o OAuth

A identidade do agente pode permitir que o agente aceda a serviços de terceiros em seu nome através da integração com o Secret Manager.

Para configurar a integração com o Secret Manager, primeiro tem de armazenar as credenciais auxiliares (ID do cliente ou segredo do cliente) para aceder aos serviços de terceiros no Secret Manager (no projeto do consumidor onde o agente é gerido durante o ciclo de vida) através dos seguintes passos:

  1. Crie um novo contentor no Secret Manager.

  2. Obtenha o ID de cliente ou o segredo do cliente do fornecedor da app de terceiros.

  3. Adicione o ID de cliente ou o segredo do cliente ao Secret Manager.

  4. Restrinja o acesso a estas 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" \

Assim que o segredo é armazenado, o agente pode aceder a estas credenciais durante a execução através do respetivo identificador principal e da biblioteca de autenticaçãoGoogle Cloud padrão automaticamente como parte da credencial predefinida da aplicação.

# 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 de cliente e o segredo do cliente, já pode criar a sua ferramenta e configurar a autenticação baseada em OAuth.

O exemplo seguinte usa um agente desenvolvido pelo Agent Development Kit (ADK). A autenticação baseada em OAuth está integrada 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, ocorre o seguinte (se usar o ADK localmente através da Web do ADK, os passos são automatizados na Web do ADK e no back-end do ADK):

  1. Acede ao agente e o agente decide que tem de invocar a ferramenta (por exemplo, o Slack).

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

  3. O front-end analisa o objeto authConfig e é feito o redirecionamento para a página de autorização de terceiros. Depois de iniciar sessão, é feito o redirecionamento para o frontend do agente e o código de autorização é enviado para o backend do ADK.

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

Se implementar um agente ADK no tempo de execução do Vertex AI Agent Engine, tem de criar um frontend personalizado e migrar a autenticação ADK-web ou o código de redirecionamento para o frontend para realizar a mesma integração do OAuth.

Aceda a serviços de terceiros através de chaves de API

A identidade do agente pode permitir que o agente aceda a serviços de terceiros e atue em seu nome através de chaves de API. Primeiro, tem de armazenar as chaves da API para acesso aos serviços de terceiros no Secret Manager e, em seguida, obter estas 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,
)

Registe a atividade do agente

Se ativar o Cloud Logging, pode ver os registos de que agente e utilizadores acederam a um Google Cloud recurso.

  • Quando o agente age em nome de um utilizador, os registos mostram as identidades do agente e do utilizador.

  • Quando o agente está a agir por sua própria autoridade, os registos mostram apenas a identidade do agente.

Indique os agentes e as respetivas identidades

Pode ver a lista das identidades dos seus agentes no Vertex AI Agent Engine através da Google Cloud consola e da linha de comandos.

Consola

  1. Na Google Cloud consola, aceda à página Vertex AI Agent Engine.

    Aceda ao motor do agente

    Os agentes implementados que fazem parte do projeto selecionado aparecem na lista. Pode usar o campo Filtrar para filtrar a lista pela coluna especificada.

  2. Para cada agente, a identidade do agente é apresentada na coluna Identidade.

API REST

Pode obter a identidade do agente quando obtém uma instância do Agent Engine através da 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 do serviço ou da conta de serviço associado à instância do Agent Engine.

O que se segue?