Autenticarsi utilizzando l'autorità dell'agente

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

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

Prima di iniziare

Verifica di aver scelto il metodo di autenticazione corretto.
Crea ed esegui il deployment di un agente con l'identità dell'agente abilitata.
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 Google Cloud , chiedi all'amministratore di concederti i seguenti ruoli IAM sulla risorsa di destinazione:

Per concedere l'accesso a un agente:
- Project IAM Admin (roles/resourcemanager.projectIamAdmin)
- Security Admin (roles/iam.securityAdmin)
Ruoli consigliati per l'identità dell'agente:
- Editor del contesto dell'agente (roles/aiplatform.agentContextEditor)
- Accesso predefinito dell'agente (roles/aiplatform.agentDefaultAccess)
- Utente Vertex AI (roles/aiplatform.user)
- Consumer Service Usage (roles/serviceusage.serviceUsageConsumer)
- Browser (roles/browser)
- Storage Object Viewer (roles/storage.objectViewer)

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.

Concedere l'accesso agli agenti

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

Nelle policy di autorizzazione IAM, le identità dell'agente utilizzano identificatori di entità.

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

Console

Nella console Google Cloud , vai alla pagina IAM della risorsa a cui vuoi concedere l'accesso.
- Per un progetto, vai alla pagina IAM:
  Vai alla pagina IAM
- Per le altre risorse, vai alla pagina della risorsa e fai clic sulla scheda Autorizzazioni o IAM.
Fai clic su Concedi l'accesso.
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/*
Nel campo Seleziona un ruolo, cerca e seleziona il ruolo che vuoi concedere.
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 servizio Google Cloud (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 principale 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: l'ID della tua organizzazione Google Cloud .
PROJECT_NUMBER: il tuo Google Cloud numero di progetto.
LOCATION: la posizione del tuo agente (ad esempio, us-central1). (Obbligatorio solo per l'accesso di un singolo agente.)
ENGINE_ID: l'ID del motore di ragionamento. (Obbligatorio solo per l'accesso di un singolo agente.)
ROLE: il ruolo IAM che vuoi concedere.

Fare riferimento all'identità dell'agente nel codice

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

Il seguente snippet Python mostra come utilizzare manualmente le credenziali dell'identità dell'agente per chiamare l'API Cloud Vision utilizzando 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) Disattivare 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 di possesso (DPoP) autenticando il token di accesso dell'agente. Il criterio impone inoltre l'utilizzo di mTLS per accedere al gateway dell'agente. In questo modo, i token associati al certificato possono essere utilizzati solo dall'ambiente di runtime attendibile previsto (ad esempio, un container Cloud Run). Questa base di sicurezza rende le credenziali rubate non riutilizzabili, contribuendo a proteggere dal furto di credenziali e dal takeover dell'account (ATO).

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

Per disattivare la funzionalità, 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 attivata. 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]"],
    },
)