Agent-Identität mit Vertex AI Agent Engine verwenden

Auf dieser Seite wird beschrieben, wie Sie die Agent-Identität von Identity and Access Management (IAM) verwenden, um Sicherheits- und Zugriffs verwaltungsfunktionen bereitzustellen, wenn Sie Agents in der Vertex AI Agent Engine-Laufzeit verwenden.

Übersicht

Die Agent-Identität bietet eine Identität pro Agent, die einen Ansatz mit minimalen Berechtigungen ermöglicht und an den Lebenszyklus des Agents gebunden ist. Dadurch ist die Agent-Identität ein sichereres Hauptkonto als Dienstkonten. Vorhandene Zugriffsverwaltungsfunktionen über IAM unterstützen die Agent-Identität, um eine starke Governance zu ermöglichen.

Die Anmeldedaten der Agent-Identität werden standardmäßig durch eine von Google verwaltete Richtlinie für den kontextsensitiven Zugriff (Context-Aware Access, CAA) geschützt. Diese Richtlinie erzwingt die mTLS Bindung , um sicherzustellen, dass die Anmeldedaten des Agents in Form von zertifikatsgebundenen Tokens nur aus der beabsichtigten, vertrauenswürdigen Laufzeitumgebung (z. B. einem Cloud Run -Container) verwendet werden können. Diese Sicherheitsbaseline verhindert, dass gestohlene Anmeldedaten wiedergegeben werden können, und schützt so vor Anmeldedatendiebstahl und Kontoübernahme (Account Takeover, ATO).

Auf dieser Seite werden die folgenden Themen behandelt:

Beschränkungen

Beachten Sie beim Planen Ihres Projekts die folgenden Einschränkungen:

  • Agent-Identitäten können keine Rollen für Legacy-Buckets (storage.legacyBucketReader, storage.legacyBucketWriter oder storage.legacyBucketOwner) für Cloud Storage-Buckets zugewiesen werden.

  • Wir empfehlen, die Agent-Identität nur in Testumgebungen zu verwenden.

Agent mit Agent-Identität erstellen

Sie können Agents, die Sie in der Vertex AI Agent Engine bereitstellen, beim Erstellen Ihrer Agent Engine-Instanz eine eindeutige Identität zuweisen. Die Identität ist an die Agent-Ressourcen-ID der Vertex AI Agent Engine gebunden und unabhängig vom Agent-Framework, das Sie zum Entwickeln des Agents verwendet haben.

Beim Erstellen einer Agent-Identität haben Sie folgende Möglichkeiten:

  • Agent Engine-Instanz erstellen, ohne Agent-Code bereitzustellen: Wenn Sie IAM-Richtlinien einrichten möchten, bevor Sie den Agent bereitstellen, können Sie eine Agent-Identität erstellen, ohne den Agent-Code bereitzustellen. Erstellen Sie dazu eine Agent Engine-Instanz mit nur dem Feld 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}
)

    Nachdem Sie die Agent Engine-Instanz mit der Agent-Identität erstellt haben, können Sie mit agent_engine.update(...) Agent-Code hinzufügen.

  • Agent Engine-Instanz erstellen und gleichzeitig Agent-Code bereitstellen: Wenn Sie die Agent-Identität beim Bereitstellen des Agent-Codes bereitstellen möchten, verwenden Sie das Vertex AI SDK für Python und das identity_type=AGENT_IDENTITY Flag.

    Definieren Sie den Agent in Ihrem bevorzugten Framework:

    from google.adk.agents import Agent

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

    Stellen Sie ihn dann bereit:

    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
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity
remote_app = client.agent_engines.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
    "staging_bucket": f"gs://"BUCKET _NAME",
  },
)

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

    Dabei ist BUCKET_NAME der Name Ihres Cloud Storage-Bucket.

Die Agent Engine-Instanz wird mit einer schreibgeschützten, vom System bestätigten Agent Identität (einer Hauptkonto-ID) erstellt:

# 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

Die folgenden Teile werden Ihnen automatisch als Teil der Agent-Identität bereitgestellt:

  • TRUST_DOMAIN: Eine Vertrauensdomain wird für Sie bereitgestellt, wenn Sie die Vertex AI API aktivieren:

    • Wenn Sie eine Organisation haben, wird die Vertrauensdomain auf Organisationsebene mit dem Format agents.global.org-ORGANIZATION_ID.system.id.goog erstellt.

    • Wenn Ihr Projekt keine Organisation hat, wird eine Vertrauensdomain auf Projektebene mit dem Format agents.global.project-PROJECT_NUMBER.system.id.goog erstellt.

  • NAMESPACE: Der unveränderliche Ressourcenpfad des Agents.

  • AGENT_NAME: Die unveränderliche agent-reasoning-engine-id.

Die Agent-Identität basiert auf SPIFFE. Wir stellen außerdem automatisch ein x509-Zertifikat für den Agent mit derselben Identität für die sichere Authentifizierung bereit und verwalten es.

Sie können die Identität über die Vertex AI Agent Engine-Console und API aufrufen. Google Cloud

Zugriff auf Google Cloud APIs und Dienste mit Agent-Identität

Nachdem Sie einen Agent mit Agent-Identität erstellt haben, können Sie dem Agent mit den folgenden IAM-Richtlinien Zugriff auf Google Cloud APIs und Dienste gewähren oder verweigern:

  • Zulassungsrichtlinien: Gewähren Sie einem Agent Zugriff auf eine Google Cloud Ressource.

  • Ablehnungsrichtlinien: Verweigern Sie einem Agent den Zugriff auf eine Google Cloud Ressource.

Zugriff auf einen Agent gewähren

Gewähren Sie der Agent-Identität IAM-Berechtigungen. Wir empfehlen die folgenden Rollen:

  • roles/aiplatform.expressUser: Gewährt Zugriff auf Inferenz, Sitzungen und Arbeitsspeicher.

  • roles/serviceusage.serviceUsageConsumer: Gewährt dem Agent die Berechtigung, das Kontingent des Projekts und das Vertex AI SDK zu verwenden.

  • roles/browser: Gewährt Zugriff auf grundlegende Google Cloud Funktionen.

Möglicherweise sind zusätzliche Berechtigungen erforderlich, wenn Sie Logging, Messwerte und die Cloud API-Registrierung verwenden, sowie für alle anderen Ressourcen, die Sie Ihrem Agent zur Verfügung stellen möchten. Weitere Beispiele finden Sie weiter unten.

Erstellen Sie eine IAM-Zulassungsrichtlinie, um einem Agent eine IAM-Rolle zuzuweisen:

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

Ersetzen Sie Folgendes:

  • ORGANIZATION_ID: Die ID für Ihre Organisation.

  • PROJECT_NUMBER: Ihre Projektnummer.

  • LOCATION: Ihre Region. Informationen zu den unterstützten Regionen für die Vertex AI Agent Engine finden Sie hier.

  • AGENT_ENGINE_ID: Die Ressourcen-ID Ihrer Agent Engine-Instanz.

  • ROLE_NAME ist der Name der Rolle, die Sie zuweisen möchten. Beispiel: roles/vision.user. Eine Liste der vordefinierten Rollen finden Sie unter Informationen zu Rollen.

Sobald IAM konfiguriert ist, werden die Standardanmeldedaten für Anwendungen des Google Cloud SDK's Application Default Credentials automatisch die Agent-Identität verwenden, um die Authentifizierung bei Google Cloud Ressourcen durchzuführen.

Zugriff auf mehrere Agents gewähren

Sie können allen Agent Engine-Agents in einem bestimmten Projekt oder in der gesamten Organisation eine IAM-Rolle zuweisen.

Verwenden Sie einen der folgenden Befehle, um allen Agent Engine-Agents in einem Projekt eine Rolle zuzuweisen.

Wenn Ihr Projekt zu einer Organisation gehört:

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

Wenn Ihr Projekt nicht zu einer Organisation gehört:

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

Es kann einfacher sein, allen Agents im Projekt allgemeine Berechtigungen wie Kontingente, Logging oder Zugriff auf Modelle zu gewähren, um Bereitstellungen zu vereinfachen. Gewähren Sie dann einzelnen Agents spezifische, eingeschränkte Berechtigungen für sensiblere Berechtigungen wie den Zugriff auf Daten. Solche Berechtigungen können jederzeit nach der ersten Verwendung der Funktion für die Agent-Identität in einer Organisation oder einem Projekt gewährt werden. Sie können also vor der Bereitstellung des Agents erfolgen.

Mit den folgenden Befehlen werden beispielsweise allen Agents in einem Projekt grundlegende Rollen zugewiesen:

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

So weisen Sie allen Agent Engine-Agents in einer Organisation eine Rolle zu:

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

Zugriff auf einen Agent verweigern

Wenn Sie einem Agent den Zugriff auf Ressourcen verweigern möchten, können Sie die IAM-Ablehnungs richtlinie verwenden oder eine Richtlinie für die Zugriffsgrenze des Hauptkontos einrichten.

  • Verweigern Sie dem Agent mit der IAM-Ablehnungsrichtlinie den Zugriff auf bestimmte Ressourcen.

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

  • Richten Sie eine Zugriffsgrenze für das Hauptkonto ein, um die Ressourcen einzuschränken, auf die der Agent zugreifen darf, obwohl er möglicherweise andere Berechtigungen hat:

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

Zugriff auf Drittanbieterdienste mit delegierter Berechtigung über OAuth

Die Agent-Identität kann dem Agent den Zugriff auf Drittanbieterdienste in Ihrem Namen ermöglichen, indem sie in Secret Manager eingebunden wird.

Um die Einbindung in Secret Manager einzurichten, müssen Sie zuerst die Hilfsanmeldedaten (Client-ID oder Clientschlüssel) für den Zugriff auf die Drittanbieterdienste in Secret Manager (im Consumer-Projekt, in dem der Lebenszyklus des Agents verwaltet wird) speichern. Führen Sie dazu die folgenden Schritte aus:

  1. Erstellen Sie einen neuen Container in Secret Manager.

  2. Rufen Sie die Client-ID oder den Clientschlüssel vom Drittanbieter der App ab.

  3. Fügen Sie die Client-ID oder den Clientschlüssel zu Secret Manager hinzu.

  4. Beschränken Sie den Zugriff auf diese Anmeldedaten basierend auf der Agent-ID (einer Hauptkonto-ID):

    # 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 --data-file=oauth-secret

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

Sobald das Secret gespeichert ist, kann der Agent während der Laufzeit mit seiner Hauptkonto-ID und der Standard Google Cloud authentifizierungsbibliothek automatisch als Teil der Standardanmeldedaten für Anwendungen auf diese Anmeldedaten zugreifen.

# 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
from google.auth import default

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

Mit der Client-ID und dem Clientschlüssel können Sie jetzt Ihr Tool erstellen und die OAuth-basierte Authentifizierung konfigurieren.

Im folgenden Beispiel wird ein Agent verwendet, der mit dem Agent Development Kit (ADK) entwickelt wurde. Die OAuth-basierte Authentifizierung wird im Rahmen der Toolerstellung in AuthCredential und OAuth2Auth eingebunden:

import os
import asyncio

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.5-flash',
   name='enterprise_assistant',
   instruction='Help user integrate with Slack and post messages to Slack.',
   tools=[slack_toolset],
)

Während der Laufzeit geschieht Folgendes (wenn Sie ADK lokal über das ADK-Web verwenden, werden die Schritte im ADK-Web und im ADK-Back-End automatisiert):

  1. Sie greifen auf den Agent zu und der Agent entscheidet, dass er das Tool aufrufen muss (z. B. Slack).

  2. Die in ADK programmierten Tools (mit auth_scheme und auth_credential) geben ein authConfig-Objekt an das Front-End zurück (einschließlich Weiterleitungs-URI und Client-ID).

  3. Das Front-End parst das authConfig-Objekt und Sie werden zur Autorisierungsseite des Drittanbieters weitergeleitet. Nachdem Sie sich angemeldet haben, werden Sie zum Front-End des Agents weitergeleitet und der Autorisierungscode wird an das ADK-Back-End gesendet.

  4. Das Back-End verwendet den Autorisierungscode, um ein Zugriffstoken für den Drittanbieterdienst abzurufen, und führt das Tool weiter aus.

Wenn Sie einen ADK-Agent in der Vertex AI Agent Engine-Laufzeit bereitstellen, müssen Sie ein benutzerdefiniertes Front-End erstellen und die ADK-Webauthentifizierung oder den Weiterleitungscode in Ihr Front-End migrieren, um dieselbe OAuth-Einbindung durchzuführen.

Zugriff auf Drittanbieterdienste mit API-Schlüsseln

Die Agent-Identität kann dem Agent den Zugriff auf Drittanbieterdienste ermöglichen und in Ihrem Namen mit API-Schlüsseln agieren. Sie müssen zuerst die API-Schlüssel für den Zugriff auf die Drittanbieterdienste in Secret Manager speichern und dann diese Anmeldedaten aus Secret Manager abrufen.

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

# Access secret is defined in the code blocks above
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,
)

Agent-Aktivität protokollieren

Wenn Sie Cloud Logging aktivieren, können Sie Protokolle darüber aufrufen, welcher Agent und welche Nutzer auf eine Google Cloud Ressource zugegriffen haben.

  • Wenn der Agent im Namen eines Nutzers agiert, werden in den Protokollen sowohl die Identität des Agents als auch die des Nutzers angezeigt.

  • Wenn der Agent in eigener Verantwortung agiert, wird in den Protokollen nur die Identität des Agents angezeigt.

Agents und ihre Identitäten auflisten

Sie können die Liste Ihrer Agent-Identitäten in der Vertex AI Agent Engine über die Google Cloud Console und die Befehlszeile aufrufen.

Console

  1. Rufen Sie in der Google Cloud Console die Seite Vertex AI Agent Engine auf.

    Zu Agent Engine

    Bereitgestellte Agents, die Teil des ausgewählten Projekts sind, werden in der Liste angezeigt. Mit dem Feld Filter können Sie die Liste nach der angegebenen Spalte filtern.

  2. Für jeden Agent wird die Agent-Identität in der Spalte Identität aufgeführt.

REST API

Sie können die Agent-Identität abrufen, wenn Sie eine Agent Engine-Instanz abrufen mit der REST API.

Die Antwort enthält die Agent-Identität im folgenden Format:

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

Bei Agent Engine-Instanzen, die keine Agent-Identität verwenden, enthält das Feld effectiveIdentity den Namen des Dienst-Agents oder Dienstkontos, der bzw. das mit der Agent Engine-Instanz verknüpft ist.

Kontextsensitiven Zugriff (Context-Aware Access, CAA) deaktivieren

In Sonderfällen, z. B. bei bestimmten Anforderungen an die Tokenfreigabe zwischen Agents, können Sie die Standardrichtlinie für den kontextsensitiven Zugriff deaktivieren. Von dieser Maßnahme wird dringend abgeraten, da sie einen Agent anfällig für Anmeldedatendiebstahl macht.

Deaktivieren Sie die Standardrichtlinie für den kontextsensitiven Zugriff (Context-Aware Access, CAA), indem Sie beim Erstellen Ihrer Agent Engine-Instanz die folgende Umgebungs variable festlegen :

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

Nächste Schritte