Agent-Identität mit Vertex AI Agent Engine verwenden

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

Übersicht

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

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 Legacy-Bucket-Rollen (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 Vertex AI Agent Engine bereitstellen, beim Erstellen Ihrer Agent Engine-Instanz mit einer eindeutigen Identität bereitstellen. 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 die folgenden Optionen:

  • 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 beim Bereitstellen von Agent-Code erstellen: Wenn Sie die Agent-Identität beim Bereitstellen Ihres Agent-Codes bereitstellen möchten, verwenden Sie das Vertex AI SDK für Python und das Flag identity_type=AGENT_IDENTITY:

    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(
      agent=app,
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
          "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
          "staging_bucket": f"gs://"BUCKET _NAME",
      },
)

    BUCKET_NAME ist dabei der Name Ihres Cloud Storage-Buckets.

Die Agent Engine-Instanz wird mit einer schreibgeschützten, vom System bestätigten Agent-Identität (einer Hauptkonto-Kennung) 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 im Rahmen der Agentenidentität automatisch bereitgestellt:

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

    • Wenn Sie eine Organisation haben, wird die Vertrauenswürdigkeitsdomain auf Organisationsebene im Format agents.global.org-ORGANIZATION_ID.system.id.goog erstellt.

    • Wenn Ihr Projekt keiner Organisation angehört, wird eine Vertrauenswürdige Domain auf Projektebene mit dem Format agents.global.project-PROJECT_NUMBER.system.id.goog erstellt.

  • NAMESPACE: Der unveränderliche Ressourcenpfad des Agenten.

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

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

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

Mit der Identität des Kundenservicemitarbeiters auf Google Cloud APIs und ‑Dienste zugreifen

Nachdem Sie einen Agent mit einer 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 einem Agent Zugriff auf eine Google Cloud -Ressource.

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

Zugriff auf einen Agenten gewähren

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

  • roles/aiplatform.expressUser: Zugriff auf die Ausführung von Inferenz, Sitzungen und Arbeitsspeicher gewähren.

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

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. Unterstützte Regionen für Vertex AI Agent Engine

  • 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 automatisch verwendet, um die Agent-Identität für die Authentifizierung beiGoogle Cloud -Ressourcen zu verwenden.

Zugriff auf einen Agenten verweigern

Wenn Sie einem Agent den Zugriff auf Ressourcen verweigern möchten, können Sie die IAM-Ablehnungsrichtlinie verwenden oder eine Principal Access Boundary-Richtlinie einrichten.

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

    // 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 Principal Access Boundary ein, um die Ressourcen einzuschränken, auf die der Agent trotz anderer Berechtigungen, die er möglicherweise hat, zugreifen darf:

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

Über OAuth mit delegierter Berechtigung auf Drittanbieterdienste zugreifen

Die Agent-Identität kann es dem Agent ermöglichen, in Ihrem Namen auf Drittanbieterdienste zuzugreifen, indem sie in Secret Manager integriert wird.

Um die Integration mit Secret Manager einzurichten, müssen Sie zuerst die zusätzlichen Anmeldedaten (Client-ID oder Clientschlüssel) für den Zugriff auf die Drittanbieterdienste in Secret Manager (im Verbraucherprojekt, in dem der Agent verwaltet wird) speichern. Gehen Sie dazu so vor:

  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 Haupt-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 "gcp-client-secret-1a2b3c4d"

# 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 Haupt-ID und der standardmäßigenGoogle Cloud -Authentifizierungsbibliothek automatisch als Teil der Application Default Credentials 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

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 ist als Teil der Tool-Erstellung in die Methoden authenticationScheme und authCredential eingebunden:

import os

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.0-flash',
   name='enterprise_assistant',
   instruction='Help user integrate with Slack and post messages to Slack.',
   tools=userinfo_toolset.get_tools(),
)

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

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

  2. Die im ADK programmierten Tools (mit auth_scheme und auth_credential) geben ein authConfig-Objekt an das Frontend zurück, das den Weiterleitungs-URI und die Client-ID enthält.

  3. Das Frontend parst das authConfig-Objekt und Sie werden zur Autorisierungsseite des Drittanbieters weitergeleitet. Nach der Anmeldung werden Sie zum Frontend des Kundenservicemitarbeiters weitergeleitet und der Autorisierungscode wird an das ADK-Backend gesendet.

  4. Das Backend 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-Laufzeitumgebung bereitstellen, müssen Sie ein benutzerdefiniertes Frontend erstellen und den ADK-Webauthentifizierungs- oder Weiterleitungscode in Ihr Frontend migrieren, um dieselbe OAuth-Integration durchzuführen.

Mit API-Schlüsseln auf Drittanbieterdienste zugreifen

Die Identität des Agents kann es ihm ermöglichen, mithilfe von API-Schlüsseln auf Drittanbieterdienste zuzugreifen und in Ihrem Namen zu handeln. 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

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äten protokollieren

Wenn Sie Cloud Logging aktivieren, können Sie Logs ansehen, in denen aufgezeichnet wird, welcher Agent und welche Nutzer auf eine Google Cloud Ressource zugegriffen haben.

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

  • Wenn der Agent eigenständig handelt, wird in den Logs nur die Identität des Agents angezeigt.

KI‑Agents und ihre Identitäten auflisten

Sie können die Liste Ihrer Agent-Identitäten in Vertex AI Agent Engine über die Google Cloud Konsole 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 Filtern können Sie die Liste nach der von Ihnen angegebenen Spalte filtern.

  2. Die Identität jedes Agenten wird in der Spalte Identität aufgeführt.

REST API

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

Die Antwort enthält die Identität des Kundenservicemitarbeiters 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 Dienst-Agent- oder Dienstkontonamen, der der Agent Engine-Instanz zugeordnet ist.

Nächste Schritte