Autenticarsi utilizzando l'autorità dell'agente

Gli agenti possono accedere alle Google Cloud API e ad altre risorse utilizzando la propria autorità. Ti consigliamo di utilizzare questo metodo per gli agenti ospitati su Google Cloud per interagire con altri Google Cloud servizi.

Quando un agente agisce di propria autorità, utilizza la sua identità SPIFFE principale per richiedere Google Cloud token di accesso.

Google Cloud

Prima di iniziare

  1. Verifica di aver scelto il metodo di autenticazione corretto.
  2. Crea ed esegui il deployment di un agente con l'identità dell'agente abilitata.
  3. Verifica di disporre dei ruoli necessari per completare questa attività.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per concedere a un agente l'accesso ai servizi, chiedi all'amministratore di concederti i seguenti ruoli IAM sulla risorsa di destinazione: Google Cloud

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

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Concedi l'accesso agli agenti

Per consentire all'agente di accedere a un Google Cloud servizio, devi concedere all' identità dell'agente i ruoli richiesti sulla risorsa di destinazione.

Nelle policy di autorizzazione IAM, le identità degli agenti utilizzano identificatori di entità.

Per concedere a un agente l'accesso a una risorsa, utilizza la Google Cloud console o la gcloud CLI.

Console

  1. Nella Google Cloud console, vai alla pagina IAM della risorsa a cui vuoi concedere l'accesso.
    • Per un progetto, vai alla pagina IAM:

      Vai alla pagina IAM

    • Per altre risorse, vai alla pagina della risorsa e fai clic sulla scheda Autorizzazioni o IAM.
  2. Fai clic su Concedi accesso.
  3. Nel campo Nuove entità, inserisci l'identificatore dell'entità che corrisponde al livello di accesso che vuoi concedere:
    • Un singolo agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Tutti gli agenti di un progetto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Tutti gli agenti di un'organizzazione: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  4. Nel campo Seleziona un ruolo, cerca e seleziona il ruolo che vuoi concedere.
  5. Fai clic su Salva.

Google Cloud CLI

Per concedere a un agente l'accesso a una risorsa, esegui questo comando: 
gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Sostituisci quanto segue:

  • SERVICE: il Google Cloud servizio (ad esempio, storage o bigquery).
  • RESOURCE_NAME: il nome della risorsa (ad esempio il nome del bucket o l'ID del set di dati).
  • PRINCIPAL_IDENTIFIER: l'identificatore dell'entità che corrisponde al livello di accesso che vuoi concedere:
    • Un singolo agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Tutti gli agenti di un progetto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Tutti gli agenti di un'organizzazione: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  • ORGANIZATION_ID: il tuo Google Cloud ID organizzazione.
  • PROJECT_NUMBER: il tuo Google Cloud numero di progetto.
  • LOCATION: la località dell'agente (ad esempio us-central1). (Obbligatorio solo per l'accesso a un singolo agente.)
  • ENGINE_ID: l'ID del motore di ragionamento. (Obbligatorio solo per l'accesso a un singolo agente.)
  • ROLE: il ruolo IAM che vuoi concedere.

Fai riferimento all'identità dell'agente nel codice

Le Google Cloud librerie client utilizzano automaticamente l'identità dell'agente quando il tuo agente viene eseguito il deployment in un ambiente supportato Google Cloud .

Il seguente snippet Python mostra come utilizzare manualmente le credenziali dell'identità dell'agente per chiamare l'API Cloud Vision utilizzando l'Agent Development Kit (ADK).

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

(Facoltativo) Disattiva l'accesso sensibile al contesto

Un criterio di accesso sensibile al contesto gestito da Google predefinito contribuisce a proteggere le credenziali dell'identità dell'agente. Oltre al gateway dell'agente, il criterio applica la dimostrazione della prova di possesso (DPoP) autenticando il token di accesso dell'agente. Il criterio impone anche l'utilizzo di mTLS per accedere al gateway dell'agente. In questo modo, i token associati ai certificati possono essere utilizzati solo dall'ambiente di runtime attendibile previsto (ad esempio, un container Cloud Run). Questa baseline di sicurezza impedisce la riproduzione delle credenziali rubate, contribuendo a proteggere dal furto di credenziali e dalla violazione degli account (ATO).

In rari casi, ad esempio requisiti specifici di condivisione dei token tra gli agenti, se devi inserire il token direttamente nell'intestazione o se l'agente non può eseguire l'autenticazione con un errore 401 UNAUTHENTICATED, puoi disattivare il criterio di accesso sensibile al contesto predefinito. La disattivazione rimuove la protezione del binding dei token, rendendo questi token di accesso di breve durata vulnerabili al furto o agli attacchi di riproduzione. Pertanto, la disattivazione non è consigliata.

Per disattivare, imposta la seguente variabile di ambiente quando esegui il deployment dell'agente:

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

Esegui il deployment dell'agente

Quando esegui il deployment dell'agente su Google Cloud, assicurati che l'identità dell'agente sia abilitata. Se esegui il deployment in Agent Runtime, utilizza il flag identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI 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 (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

Passaggi successivi