Utilizzare Agent Identity con Agent Runtime

L'utilizzo dell'identità dell'agente su Agent Runtime fornisce un'identità sicura per agente che consente un approccio con privilegio minimo alla gestione degli accessi. Questo documento spiega come creare agenti con identità degli agenti, autorizzare l'accesso alle APIGoogle Cloud e gestire le credenziali per i servizi di terze parti.

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à di sicurezza più sicura rispetto ai service account. I controlli di gestione degli accessi esistenti tramite IAM supportano l'identità dell'agente per consentire una governance efficace.

Le credenziali di identità dell'agente sono protette per impostazione predefinita tramite una policy di accesso sensibile al contesto (CAA) gestita da Google. Questa policy applica l'associazione mTLS per garantire che le credenziali dell'agente sotto forma di token associati al certificato possano essere utilizzate solo dall'ambiente di runtime attendibile previsto (ad esempio un container Cloud Run). Questa base di riferimento per la sicurezza rende le credenziali rubate non riproducibili, proteggendo dal furto di credenziali e dal takeover dell'account (ATO).

Questa pagina tratta i seguenti argomenti:

Limitazioni

Alle identità degli agenti non possono essere concessi ruoli bucket legacy (storage.legacyBucketReader, storage.legacyBucketWriter o storage.legacyBucketOwner) sui bucket Cloud Storage.

Crea un agente con l'identità dell'agente

Puoi eseguire il provisioning degli agenti di cui esegui il deployment in Agent Runtime con un'identità univoca al momento della creazione dell'istanza di Agent Runtime. L'identità è legata all'ID risorsa dell'agente di Agent Runtime ed è indipendente dal framework dell'agente utilizzato per sviluppare l'agente.

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

  • Crea un'istanza di runtime dell'agente senza eseguire il deployment del codice dell'agente: se vuoi configurare le policy 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 Runtime con solo il campo identity_type:

    import agentplatform
from agentplatform import types

client = agentplatform.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.runtimes.create(
  config={
    "display_name": "identity-for-agent",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
  },
)

    Dopo aver creato l'istanza Agent Runtime con l'identità dell'agente, puoi aggiungere il codice dell'agente utilizzando client.runtimes.update(...).

  • Crea un'istanza Agent Runtime 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 Agent Platform per Python e il flag identity_type=AGENT_IDENTITY.

    Definisci l'agente nel framework che preferisci:

    from google.adk.agents import Agent

agent = Agent(
    model="gemini-2.5-flash",
    name="minimal_agent",
    instruction="You are a helpful assistant.",
)

    Poi, eseguine il deployment:

    import agentplatform
from agentplatform import types
from agentplatform.frameworks import AdkApp

# Initialize the Agent Platform client with v1beta1 API for agent identity support
client = agentplatform.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.runtimes.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-agentplatform[adk,runtimes]"],
    "staging_bucket": f"gs://"BUCKET_NAME",
  },
)

print(f"Effective Identity: {remote_app.api_resource.spec.effective_identity}")

    dove BUCKET_NAME è il nome del tuo bucket Cloud Storage.

  • Esegui il deployment degli agenti utilizzando l'interfaccia a riga di comando degli agenti: l'interfaccia a riga di comando degli agenti è ideale per gli studenti, la prototipazione e i test rapidi, in quanto offre una soluzione di deployment rapida con risorse di base per il monitoraggio. Il seguente comando esegue il deployment dell'agente:

    agents-cli deploy --agent-identity

  • Esegui il deployment degli agenti con l'identità dell'agente utilizzando il deployment ADK: configura l'agente con ADK. Prima di eseguire adk deploy, esegui i seguenti comandi nella cartella dell'agente per aggiungere un file di configurazione con l'identità dell'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

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

# 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 a provisioning automatico per te nell'ambito dell'identità dell'agente:

  • TRUST_DOMAIN: un dominio di attendibilità viene eseguito il provisioning per te quando abiliti l'API Agent Platform:

    • Se hai un'organizzazione, il dominio di attendibilità 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 di attendibilità a livello di progetto con il formato agents.global.proj-PROJECT_NUMBER.system.id.goog.

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

  • AGENT_NAME: l'oggetto agent-reasoning-engine-id immutabile.

L'identità dell'agente si basa su SPIFFE. Inoltre, eseguiamo il provisioning automatico e la gestione di un certificato x509 sull'agente con la stessa identità per un'autenticazione sicura. Per impostazione predefinita, l'agente ottiene l'accesso ai propri log, metriche, accesso ai modelli, sessioni, memorie e sandbox (anteprima).

Le identità degli agenti sono dotate di ruoli roles/aiplatform.agentContextEditor e roles/aiplatform.agentDefaultAccess predefiniti, in modo che gli agenti dispongano delle autorizzazioni di base per operare.

Puoi visualizzare l'identità tramite la console Google Cloud e l'API Agent Runtime.

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

Una volta creato un agente con l'identità dell'agente, puoi concedere o negare all'agente l'accesso alle API e ai servizi Google Cloud utilizzando le seguenti policy IAM:

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

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

Concedi l'accesso a un agente

Concedi le 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 per utilizzare la quota del progetto e l'SDK Agent Platform.

  • roles/browser: concedi l'accesso alle funzionalità di base di Google Cloud .

  • roles/secretmanager.secretAccessor: concedi all'agente l'accesso ai secret in Secret Manager. Se fai riferimento ai secret come variabili di ambiente, devi anche concedere roles/secretmanager.secretAccessor all'agente di servizio di Agent Platform (service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) in modo che possa recuperare i valori dei secret durante il deployment.

Potrebbero essere necessarie autorizzazioni aggiuntive se utilizzi il logging, le metriche e il registro delle API Cloud, nonché per qualsiasi altra risorsa che vuoi esporre all'agente. Vedi di seguito per altri esempi.

Crea una policy 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:

  • RESOURCE_TYPE: il tipo di risorsa (ad esempio projects o organizations).

  • RESOURCE_ID: l'ID della risorsa a cui vuoi concedere l'accesso.

  • ORGANIZATION_ID: l'ID della tua organizzazione.

  • PROJECT_NUMBER: il numero del progetto.

  • LOCATION: la tua regione. Consulta le regioni supportate per Runtime.

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

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

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

Concedi l'accesso per la delega Agent-to-Agent (A2A)

Quando progetti un sistema multi-agente in cui un agente parent richiama un subagente remoto registrato in Agent Registry, l'identità dell'agente parent deve disporre delle autorizzazioni per rilevare il subagente in Agent Registry e richiamare il relativo endpoint.

Per assicurarti che l'identità dell'agente parent disponga delle autorizzazioni necessarie per rilevare e richiamare un subagente remoto, chiedi all'amministratore di concedere i seguenti ruoli IAM all'identità dell'agente parent:

  • Consenti all'agente parent di cercare l'endpoint del subagente in fase di runtime: Agent Registry API Viewer (roles/agentregistry.viewer) sul progetto parent o sulla risorsa del registry
  • Consenti all'agente parent di inviare messaggi al subagente: Utente Agent Platform (roles/aiplatform.user) sulla risorsa del motore di ragionamento del subagente di destinazione

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

L'amministratore potrebbe anche essere in grado di concedere all'identità dell'agente parent le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.

Ad esempio, per concedere il ruolo roles/agentregistry.viewer al progetto, puoi utilizzare il seguente comando Google Cloud CLI:

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/PARENT_AGENT_ENGINE_ID" \
    --role="roles/agentregistry.viewer"

Sostituisci quanto segue:

  • ORGANIZATION_ID: l'ID della tua organizzazione.
  • PROJECT_NUMBER: il numero del progetto.
  • LOCATION: la regione in cui è stato eseguito il deployment dell'agente parent.
  • PARENT_AGENT_ENGINE_ID: l'ID risorsa dell'istanza di Agent Runtime dell'agente parent.

Concedi l'accesso a più agenti

Puoi concedere un ruolo IAM a tutti gli agenti di Agent Runtime in un progetto specifico o nell'intera organizzazione.

Per concedere un ruolo a tutti gli agenti di Agent Runtime in un progetto, utilizza uno dei seguenti comandi.

Se il tuo progetto appartiene a un'organizzazione:

# 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 il tuo progetto non appartiene a un'organizzazione:

# Grant all agents in an orgless project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.proj-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

Per semplificare i deployment, può essere più facile concedere autorizzazioni comuni, come quota, logging o accesso ai modelli, a tutti gli agenti del progetto. Quindi, concedi autorizzazioni specifiche e limitate ai singoli agenti per le autorizzazioni più sensibili, come l'accesso ai dati. La concessione di queste autorizzazioni è possibile in qualsiasi momento dopo il primo utilizzo della funzionalità di identità dell'agente all'interno di un'organizzazione o di un progetto, pertanto può essere eseguita prima del deployment dell'agente.

Ad esempio, i seguenti comandi concedono ruoli di base a tutti gli agenti di un progetto:

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

Per concedere un ruolo a tutti gli agenti Agent Runtime di un'organizzazione:

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

Nega 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 sul confine di accesso dell'entità.

  • Nega all'agente l'accesso a determinate risorse utilizzando la policy 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 un confine di accesso dell'entità per limitare le risorse a cui l'agente può accedere, nonostante le altre autorizzazioni che l'agente 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

Indicazioni su CI/CD e automazione

Le pipeline di deployment automatizzate che eliminano e ricreano gli agenti (ad esempio deployment blu-verde, ambienti di test temporanei o workflow di Terraform) possono subire una perdita silenziosa dell'accesso in fase di runtime. Poiché ogni nuovo deployment crea una nuova risorsa reasoningEngines con un ID univoco, l'agente riceve un nuovo identificatore dell'entità. Le autorizzazioni IAM concesse in precedenza all'entità precedente non vengono ereditate dalla nuova entità.

Per gestire le autorizzazioni nelle pipeline automatizzate, utilizza le seguenti strategie:

  • Recupera il nuovo ID entità in modo dinamico: acquisisci il valore spec.effectiveIdentity dalla risposta del deployment o esegui una query sull'API REST dopo il deployment per ottenere l'identità attiva dell'agente. Applica le associazioni IAM richieste a questa nuova entità come passaggio post-deployment.

    Ad esempio, puoi eseguire una query sull'identità attiva con gcloud utilizzando il seguente comando:

    gcloud ai reasoning-engines describe RESOURCE_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --format="value(spec.effectiveIdentity)"

    In Terraform, puoi creare dinamicamente l'entità dell'identità dell'agente dall'ID risorsa google_vertex_ai_reasoning_engine di cui è stato eseguito il deployment e farvi riferimento nelle associazioni IAM:

    resource "google_vertex_ai_reasoning_engine" "reasoning_engine" {
  provider = google-beta

  project      = var.project_id
  region       = var.region
  display_name = var.display_name
  description  = var.agent_description

  spec {
    agent_framework = "google-adk"
    identity_type   = "AGENT_IDENTITY"

    source_code_spec {
      inline_source {
        source_archive = filebase64(data.archive_file.agent_tarball.output_path)
      }

      python_spec {
        entrypoint_module = var.agent_python_spec.entrypoint_module
        entrypoint_object = var.agent_python_spec.entrypoint_object
        requirements_file = var.agent_python_spec.requirements_path
        version           = var.agent_python_spec.version
      }
    }

    deployment_spec {
      env {
        name  = "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY"
        value = "true"
      }

      env {
        name  = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
        value = "true"
      }
    }
  }
}

locals {
  agent_resource_id        = element(split("/", google_vertex_ai_reasoning_engine.reasoning_engine.id), -1)
  agent_identity_principal = "principal://agents.global.org-${data.google_organization.org.org_id}.system.id.goog/resources/aiplatform/projects/${data.google_project.project.number}/locations/${var.region}/reasoningEngines/${local.agent_resource_id}"
}

  • Utilizza principalSets con ambito di progetto per le autorizzazioni di base: poiché le associazioni principalSet hanno come target tutti gli agenti di un progetto, sopravvivono all'eliminazione e alla ricreazione degli agenti. Concedi ruoli comuni e non sensibili (come l'utilizzo dei servizi, il logging e l'inferenza del modello generale) all'principalSet a livello di progetto anziché alle singole entità dell'agente. Limita le associazioni di singoli principal:// a origini dati altamente sensibili.

Registra 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 in base alla propria autorità, i log mostrano solo l'identità dell'agente.

Elenca gli agenti e le loro identità

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

Console

  1. Nella console Google Cloud , vai alla pagina Deployment della piattaforma agente.

    Vai a Deployment

    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à è elencata nella colonna Identità.

API REST

Puoi recuperare l'identità dell'agente quando recuperi un'istanza di Agent Runtime 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 Runtime che non utilizzano Agent Identity, il campo effectiveIdentity contiene il nome del service agent o del account di servizio associato all'istanza di Agent Runtime.

Disattivare l'accesso sensibile al contesto (CAA)

Per impostazione predefinita, il tentativo di utilizzare un token di accesso al di fuori del runtime di Agent Runtime previsto genera il seguente errore:

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

Per i casi limite, ad esempio requisiti specifici di condivisione dei token tra gli agenti, puoi disattivare la policy CAA predefinita. Questa azione è sconsigliata, in quanto rende un agente vulnerabile al furto di credenziali.

Disattiva la policy di accesso sensibile al contesto (CAA) predefinita impostando la seguente variabile di ambiente quando crei l'istanza di Agent Runtime:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

Passaggi successivi

Guida

Scopri come gestire gli agenti di cui è stato eseguito il deployment nel runtime gestito di Agent Platform.

Guida

Utilizza un agente con Agent Platform Runtime.