Authentifizierung mit der eigenen Berechtigung eines KI-Agenten

Agenten können mit ihrer eigenen Berechtigung auf Google Cloud APIs und andere Ressourcen zugreifen. Wir empfehlen diese Methode für Agents, die auf Google Cloudgehostet werden, um mit anderen Google Cloud Diensten zu interagieren.

Wenn ein Agent eigenständig handelt, verwendet er seine primäre SPIFFE-Identität, um Google Cloud -Zugriffstokens anzufordern.

Hinweis

  1. Prüfen Sie, ob Sie die richtige Authentifizierungsmethode ausgewählt haben.
  2. Erstellen und stellen Sie einen Agenten mit aktivierter Agent-Identität bereit.
  3. Prüfen Sie, ob Sie die Rollen haben, die für diese Aufgabe erforderlich sind.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für die Zielressource zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Gewähren des Zugriffs eines Agents auf Google Cloud -Dienste benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Zugriff auf Agenten gewähren

Damit Ihr Agent auf einen Google Cloud -Dienst zugreifen kann, müssen Sie der Identität des Agents die erforderlichen Rollen für die Zielressource zuweisen.

In IAM-Zulassungsrichtlinien verwenden Agent-Identitäten Hauptkonto-IDs.

Wenn Sie einem Agent Zugriff auf eine Ressource gewähren möchten, verwenden Sie die Google Cloud -Console oder die gcloud CLI.

Console

  1. Rufen Sie in der Google Cloud Console die Seite IAM für die Ressource auf, für die Sie Zugriff gewähren möchten.
    • Rufen Sie für ein Projekt die Seite IAM auf:

      Zur IAM-Seite

    • Rufen Sie für andere Ressourcen die Seite für diese Ressource auf und klicken Sie auf den Tab Berechtigungen oder IAM.
  2. Klicken Sie auf Zugriff gewähren.
  3. Geben Sie im Feld Neue Prinzipale die Prinzipal-ID ein, die dem Zugriffsniveau entspricht, das Sie gewähren möchten:
    • Ein einzelner Agent: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Alle Agents in einem Projekt: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Alle Kundenservicemitarbeiter in einer Organisation: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  4. Suchen Sie im Feld Rolle auswählen nach der Rolle, die Sie zuweisen möchten, und wählen Sie sie aus.
  5. Klicken Sie auf Speichern.

Google Cloud CLI

Führen Sie den folgenden Befehl aus, um einem Agent Zugriff auf eine Ressource zu gewähren: 
gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Ersetzen Sie Folgendes:

  • SERVICE: Der Google Cloud Dienst (z. B. storage oder bigquery).
  • RESOURCE_NAME: Der Name der Ressource (z. B. der Bucket-Name oder die Dataset-ID).
  • PRINCIPAL_IDENTIFIER: Die Hauptkonto-ID, die der Zugriffsebene entspricht, die Sie gewähren möchten:
    • Ein einzelner Agent: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Alle Agents in einem Projekt: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Alle Kundenservicemitarbeiter in einer Organisation: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  • ORGANIZATION_ID: Ihre Google Cloud Organisations-ID.
  • PROJECT_NUMBER: Ihre Google Cloud Projektnummer.
  • LOCATION: Der Standort Ihres Kundenservicemitarbeiters (z. B. us-central1). (Nur für den Zugriff durch einen einzelnen Kundenservicemitarbeiter erforderlich.)
  • ENGINE_ID: Die ID Ihrer Reasoning Engine. (Nur für den Zugriff über einen einzelnen Agenten erforderlich)
  • ROLE: Die IAM-Rolle, die Sie zuweisen möchten.

Im Code auf die Identität des KI-Agents verweisen

Die Google Cloud -Clientbibliotheken verwenden automatisch die Agent-Identität, wenn Ihr Agent in einer unterstützten Google Cloud -Umgebung bereitgestellt wird.

Das folgende Python-Snippet zeigt, wie Sie die Anmeldedaten der Agent-Identität manuell verwenden, um die Cloud Vision API mit dem Agent Development Kit (ADK) aufzurufen.

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]}

Optional: Kontextsensitiven Zugriff deaktivieren

Eine standardmäßige, von Google verwaltete Richtlinie für den kontextsensitiven Zugriff trägt dazu bei, Anmeldedaten für die Agent-Identität zu schützen. Über das Agent Gateway hinaus erzwingt die Richtlinie den Demonstrable Proof of Possession (DPoP), indem das Zugriffstoken des Agents authentifiziert wird. Die Richtlinie erzwingt auch, dass mTLS für den Zugriff auf das Agent Gateway verwendet wird. So wird sichergestellt, dass an Zertifikate gebundene Tokens nur in der vorgesehenen, vertrauenswürdigen Laufzeitumgebung (z. B. einem Cloud Run-Container) verwendet werden können. Diese Sicherheitsbaseline macht gestohlene Anmeldedaten unbrauchbar und trägt so zum Schutz vor Anmeldedatendiebstahl und Kontoübernahmen (Account Takeover, ATO) bei.

In seltenen Fällen, z. B. bei bestimmten Anforderungen für die gemeinsame Nutzung von Tokens zwischen Agents, wenn Sie das Token direkt in den Header einschleusen müssen oder wenn sich Ihr Agent nicht mit dem Fehler 401 UNAUTHENTICATED authentifizieren kann, können Sie die standardmäßige kontextsensitive Zugriffsrichtlinie deaktivieren. Wenn Sie die Tokenbindung deaktivieren, wird der Schutz entfernt und diese kurzlebigen Zugriffstokens sind anfällig für Diebstahl oder Replay-Angriffe. Daher wird davon abgeraten, die Funktion zu deaktivieren.

Wenn Sie die Funktion deaktivieren möchten, legen Sie beim Bereitstellen des Agents die folgende Umgebungsvariable fest:

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

Agent bereitstellen

Wenn Sie Ihren Agent in Google Cloudbereitstellen, muss die Agent-Identität aktiviert sein. Wenn Sie in Agent Runtime bereitstellen, verwenden Sie das 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]"],
    },
)

Nächste Schritte