Utilizzare l'identità dell'agente con Vertex AI Agent Engine

Questa pagina descrive come utilizzare l'identità dell'agente Identity Access Management (IAM) per fornire funzionalità di sicurezza e gestione degli accessi quando utilizzi gli agenti in Vertex AI Agent Engine Runtime.

Panoramica

L'identità dell'agente fornisce un'identità per agente che consente un approccio con privilegi minimi ed è legata al ciclo di vita dell'agente, rendendo l'identità dell'agente un'entità più sicura rispetto agli account di servizio. I controlli di gestione dell'accesso esistenti tramite l'identità dell'agente di assistenza IAM per consentire una governance efficace.

Questa pagina tratta i seguenti argomenti:

Limitazioni

Quando pianifichi il progetto, tieni presenti le seguenti limitazioni:

  • Non è possibile concedere alle identità degli agenti i ruoli Legacy Bucket (storage.legacyBucketReader, storage.legacyBucketWriter o storage.legacyBucketOwner) nei bucket Cloud Storage.

  • Ti consigliamo di utilizzare l'identità dell'agente solo negli ambienti di test.

Crea un agente con l'identità dell'agente

Puoi eseguire il provisioning degli agenti di cui esegui il deployment in Vertex AI Agent Engine con un'identità unica al momento della creazione dell'istanza di Agent Engine. L'identità è associata all'ID risorsa dell'agente di Vertex AI Agent Engine ed è indipendente dal framework dell'agente che hai utilizzato per sviluppare l'agente.

Quando crei un'identità agente, hai le seguenti opzioni:

  • Crea un'istanza di Agent Engine senza eseguire il deployment del codice dell'agente: se vuoi configurare i criteri IAM prima di eseguire il deployment dell'agente, puoi creare un'identità dell'agente senza eseguire il deployment del codice dell'agente. Per farlo, crea un'istanza di Agent Engine con solo il 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}
)

    Dopo aver creato l'istanza di Agent Engine con l'identità dell'agente, puoi aggiungere il codice dell'agente utilizzando agent_engine.update(...).

  • Crea un'istanza di Agent Engine durante il deployment del codice dell'agente: se vuoi eseguire il provisioning dell'identità dell'agente durante il deployment del codice dell'agente, utilizza l'SDK Vertex AI per Python e il 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",
      },
)

    dove BUCKET_NAME è il nome del tuo bucket Cloud Storage.

L'istanza di Agent Engine viene creata con un'identità dell'agente di sola lettura attestata dal sistema (un identificatore principale):

# 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

Le seguenti parti vengono sottoposte al provisioning automatico come parte dell'identità dell'agente:

  • TRUST_DOMAIN: un dominio attendibile viene sottoposto a provisioning per te quando abiliti l'API Vertex AI:

    • Se hai un'organizzazione, il dominio attendibile viene creato a livello di organizzazione con il formato agents.global.org-ORGANIZATION_ID.system.id.goog.

    • Se il tuo progetto non ha un'organizzazione, viene creato un dominio attendibile a livello di progetto con il formato agents.global.project-PROJECT_NUMBER.system.id.goog.

  • NAMESPACE: Il percorso della risorsa immutabile dell'agente.

  • AGENT_NAME: agent-reasoning-engine-id immutabile.

L'identità dell'agente si basa su SPIFFE. Inoltre, eseguiamo il provisioning e la gestione automatici di un certificato x509 sull'agente con la stessa identità per l'autenticazione sicura.

Puoi visualizzare l'identità tramite la console e l'API Vertex AI Agent Engine Google Cloud .

Accedi Google Cloud a API e servizi utilizzando l'identità dell'agente

Dopo aver creato un agente con l'identità dell'agente, puoi concedere o negare all'agente l'accesso alle API e ai servizi Google Cloud utilizzando i seguenti criteri IAM:

  • Policy di autorizzazione: concedi a un agente l'accesso a una risorsa Google Cloud .

  • Policy di negazione: nega a un agente l'accesso a una Google Cloud risorsa.

Concedere l'accesso a un agente

Concedi autorizzazioni IAM all'identità dell'agente. Ti consigliamo i seguenti ruoli:

  • roles/aiplatform.expressUser: concedi l'accesso all'esecuzione di inferenze, sessioni e memoria.

  • roles/serviceusage.serviceUsageConsumer: concedi all'agente l'autorizzazione a utilizzare la quota del progetto e l'SDK Vertex AI.

Crea un criterio di autorizzazione IAM per concedere a un agente un ruolo IAM:

  # 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" \

Sostituisci quanto segue:

  • ORGANIZATION_ID: l'ID della tua organizzazione.

  • PROJECT_NUMBER: il numero del progetto.

  • LOCATION: La tua regione. Consulta le regioni supportate per Vertex AI Agent Engine.

  • AGENT_ENGINE_ID: l'ID risorsa dell'istanza di Agent Engine.

  • ROLE_NAME è il nome del ruolo che vuoi concedere. Ad esempio, roles/vision.user. Per un elenco dei ruoli predefiniti, consulta la sezione Informazioni sui ruoli.

Una volta configurato IAM, le credenziali predefinite dell'applicazione di Google Cloud SDK utilizzano automaticamente l'identità dell'agente per eseguire l'autenticazione alle risorseGoogle Cloud .

Negare l'accesso a un agente

Per negare a un agente l'accesso alle risorse, puoi utilizzare la policy di negazione IAM o configurare una policy di Principal Access Boundary.

  • Nega all'agente l'accesso a determinate risorse utilizzando il criterio di negazione 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"
      ]
    }
  }
]
}

  • Configura Principal Access Boundary per limitare le risorse a cui l'agente può accedere, nonostante altre autorizzazioni che potrebbe avere:

    // 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

Accedere a servizi di terze parti utilizzando l'autorizzazione delegata tramite OAuth

L'identità dell'agente può consentire all'agente di accedere a servizi di terze parti per tuo conto tramite l'integrazione con Secret Manager.

Per configurare l'integrazione con Secret Manager, devi prima archiviare le credenziali ausiliarie (ID client o client secret) per accedere ai servizi di terze parti in Secret Manager (nel progetto consumer in cui l'agente viene gestito nel ciclo di vita) seguendo questi passaggi:

  1. Crea un nuovo contenitore in Secret Manager.

  2. Ottieni l'ID client o il client secret dal fornitore dell'app di terze parti.

  3. Aggiungi l'ID client o il client secret a Secret Manager.

  4. Limita l'accesso a queste credenziali in base all'ID agente (un identificatore principale):

    # 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" \

Una volta memorizzato il secret, l'agente può accedere a queste credenziali durante l'esecuzione utilizzando il suo identificatore principale e la libreria di autenticazione Google Cloud standard automaticamente nell'ambito delle credenziali predefinite dell'applicazione.

# 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

Con l'ID client e il client secret, ora puoi creare il tuo strumento e configurare l'autenticazione basata su OAuth.

L'esempio seguente utilizza un agente sviluppato da Agent Development Kit (ADK). L'autenticazione basata su OAuth è inclusa nei metodi authenticationScheme e authCredential come parte della creazione dello strumento:

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 l'esecuzione, si verifica quanto segue (se utilizzi ADK localmente tramite ADK web, i passaggi vengono automatizzati all'interno di ADK web e del backend ADK):

  1. Accedi all'agente e l'agente decide che deve richiamare lo strumento (ad esempio Slack).

  2. Gli strumenti programmati all'interno dell'ADK (con auth_scheme e auth_credential) restituiscono un oggetto authConfig al frontend (che include l'URI di reindirizzamento e l'ID client).

  3. Il frontend analizza l'oggetto authConfig e viene reindirizzato alla pagina di autorizzazione di terze parti. Dopo aver eseguito l'accesso, viene visualizzato il frontend dell'agente e il codice di autorizzazione viene inviato al backend dell'ADK.

  4. Il backend utilizza il codice di autorizzazione per ottenere un token di accesso per il servizio di terze parti e continua a eseguire lo strumento.

Se esegui il deployment di un agente ADK in Vertex AI Agent Engine Runtime, devi creare un frontend personalizzato ed eseguire la migrazione dell'autenticazione web ADK o del codice di reindirizzamento nel frontend per eseguire la stessa integrazione OAuth.

Accedere a servizi di terze parti utilizzando le chiavi API

L'identità dell'agente può consentirgli di accedere a servizi di terze parti e agire per tuo conto utilizzando le chiavi API. Devi prima archiviare le chiavi API per l'accesso ai servizi di terze parti in Secret Manager, quindi recuperare queste credenziali da 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,
)

Registrare l'attività dell'agente

Se attivi Cloud Logging, puoi visualizzare i log di quali agenti e utenti hanno eseguito l'accesso a una risorsa Google Cloud .

  • Quando l'agente agisce per conto di un utente, i log mostrano sia l'identità dell'agente sia quella dell'utente.

  • Quando l'agente agisce di propria autorità, i log mostrano solo la sua identità.

Elenca gli agenti e le loro identità

Puoi visualizzare l'elenco delle identità degli agenti in Vertex AI Agent Engine utilizzando la console e la riga di comando. Google Cloud

Console

  1. Nella console Google Cloud , vai alla pagina Vertex AI Agent Engine.

    Vai ad Agent Engine

    Gli agenti di cui è stato eseguito il deployment che fanno parte del progetto selezionato vengono visualizzati nell'elenco. Puoi utilizzare il campo Filtra per filtrare l'elenco in base alla colonna specificata.

  2. Per ogni agente, l'identità dell'agente è elencata nella colonna Identità.

API REST

Puoi recuperare l'identità dell'agente quando ottieni un'istanza di Agent Engine utilizzando l'API REST.

La risposta include l'identità dell'agente nel seguente formato:

{
  ...
  spec: {
    "effectiveIdentity": "agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID"
  }
  ...
}

Per le istanze di Agent Engine che non utilizzano l'identità dell'agente, il campo effectiveIdentity contiene il nome del service agent o delaccount di serviziot associato all'istanza di Agent Engine.

Passaggi successivi