KI-Agentenidentität mit Agent Runtime verwenden

Die Verwendung von Agent Identity in Agent Runtime bietet eine sichere, agentenspezifische Identität, die einen Ansatz mit geringsten Berechtigungen für die Zugriffsverwaltung ermöglicht. In diesem Dokument wird beschrieben, wie Sie KI-Agenten mit Agentenidentitäten erstellen, den Zugriff aufGoogle Cloud -APIs autorisieren und Anmeldedaten für Drittanbieterdienste verwalten.

Übersicht

Die Agentenidentität bietet eine Identität pro Agent, die einen Ansatz mit geringsten Berechtigungen ermöglicht und an den Lebenszyklus des Agenten gebunden ist. Dadurch ist die Agentenidentität ein sichererer Sicherheitsprinzipal als Dienstkonten. Vorhandene Zugriffsverwaltungsfunktionen über IAM unterstützen die Agentenidentität, um eine strenge Governance zu ermöglichen.

Anmeldedaten für die 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 in der vorgesehenen, vertrauenswürdigen Laufzeitumgebung (z. B. einem Cloud Run-Container) verwendet werden können. Diese Sicherheitsgrundlage sorgt dafür, dass gestohlene Anmeldedaten nicht wiederverwendet werden können, und schützt so vor Diebstahl von Anmeldedaten und Kontoübernahme (Account Takeover, ATO).

Auf dieser Seite werden die folgenden Themen behandelt:

• KI-Agenten mit Agentenidentität erstellen: Erstellen Sie einen KI-Agenten, der bei der Bereitstellung in Agent Runtime automatisch eine eindeutige Identität erhält.

• Zugriff auf APIs von Google Cloud mit der Agentenidentität autorisieren: Verwenden Sie die bereitgestellte Agentenidentität, um dem Agenten Zugriff auf die Erstanbieter-Tools, APIs und Ressourcen von Google Cloudzu gewähren oder zu verweigern. Dazu gehört auch der Zugriff auf andere Agenten, die in Agent Runtime mit dem Agent2Agent-Protokoll (A2A) gehostet werden.

• Logging-Agent-Aktivität protokollieren: Sie können die Identität des Logging-Agenten in Protokollen für alle Google Cloud -Dienste einsehen. Bei benutzerdelegierten Abläufen werden in den Logs sowohl die Nutzeridentität als auch die Agentenidentität angezeigt.

• Agenten und Agentenidentität auflisten: Hier können Sie die Liste Ihrer Agenten und deren Identitäten in der Agent Runtime aufrufen.

• Kontextsensitiven Zugriff deaktivieren (nicht empfohlen): Deaktivieren Sie die Standardrichtlinie für den kontextsensitiven Zugriff.

Beschränkungen

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

KI-Agenten mit Agentenidentität erstellen

Sie können KI-Agenten, die Sie in der Agent Runtime bereitstellen, beim Erstellen der Agent Runtime-Instanz eine eindeutige Identität zuweisen. Die Identität ist an die Agent-Ressourcen-ID der Agent Runtime gebunden und unabhängig vom Agent-Framework, das Sie zur Entwicklung des Agents verwendet haben.

Beim Erstellen einer Agentenidentität haben Sie die folgenden Optionen:

• Agent Runtime-Instanz ohne Bereitstellung von Agent-Code erstellen: Wenn Sie IAM-Richtlinien vor der Bereitstellung des Agenten einrichten möchten, können Sie eine Agentenidentität erstellen, ohne Ihren Agenten-Code bereitzustellen. Erstellen Sie dazu eine Agent Runtime-Instanz, die nur das Feld identity_type enthält:

  import agentplatform
  from agentplatform import types
  
  client = agentplatform.Client(
    project=PROJECT_ID,
    location=LOCATION,
    http_options=dict(api_version="v1beta1")
  )
  remote_app = client.runtimes.create(
    config={
      "display_name": "identity-for-agent",
      "identity_type": types.IdentityType.AGENT_IDENTITY,
    },
  )
  

  Nachdem Sie die Agent Runtime-Instanz mit der Agentenidentität erstellt haben, können Sie mit client.runtimes.update(...) Agentencode hinzufügen.

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

  Definieren Sie den KI-Agenten im gewünschten 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 sie dann bereit:

  import agentplatform
  from agentplatform import types
  from agentplatform.frameworks import AdkApp
  
  # Initialize the Agent Platform client with v1beta1 API for agent identity support
  client = agentplatform.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.runtimes.create(
    agent=app,
    config={
      "display_name": "running-agent-with-identity",
      "identity_type": types.IdentityType.AGENT_IDENTITY,
      "requirements": ["google-cloud-agentplatform[adk,runtimes]"],
      "staging_bucket": f"gs://"BUCKET_NAME",
    },
  )
  
  print(f"Effective Identity: {remote_app.api_resource.spec.effective_identity}")
  

  BUCKET_NAME ist dabei der Name Ihres Cloud Storage-Buckets.

• Agenten mit der Agents CLI bereitstellen: Die Agents CLI eignet sich ideal für Lernende, Prototyping und schnelle Tests, da sie eine schnelle Bereitstellungslösung mit grundlegenden Ressourcen für das Monitoring bietet. Mit dem folgenden Befehl wird Ihr Agent bereitgestellt:

  agents-cli deploy --agent-identity
  

• KI-Agenten mit Agent Identity über ADK Deploy bereitstellen: KI-Agenten mit dem ADK einrichten. Bevor Sie adk deploy ausführen, führen Sie die folgenden Befehle im Ordner Ihres Agents aus, um eine Konfigurationsdatei mit der Agent-Identität hinzuzufügen.

  # Create the file
  $ touch .agent_engine_config.json
  
  # Update the file to specify that you're using Agent Identity
  $ echo '{ "identity_type": "AGENT_IDENTITY" }' > .agent_engine_config.json
  

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

• TRUST_DOMAIN: Wenn Sie die Agent Platform API aktivieren, wird eine Vertrauensdomäne für Sie bereitgestellt:

  • Wenn Sie eine Organisation haben, wird die Vertrauensdomäne auf Organisationsebene im Format agents.global.org-ORGANIZATION_ID.system.id.goog erstellt.

  • Wenn Ihr Projekt keine Organisation hat, wird auf Projektebene eine Vertrauensdomäne im Format agents.global.proj-PROJECT_NUMBER.system.id.goog erstellt.

• NAMESPACE: Der unveränderliche Ressourcenpfad des KI-Agenten.

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

Die KI-Agentenidentität basiert auf SPIFFE. Außerdem wird auf dem Agent ein x509-Zertifikat mit derselben Identität für die sichere Authentifizierung automatisch bereitgestellt und verwaltet. Standardmäßig erhält der KI-Agent Zugriff auf seine eigenen Logs, Messwerte, Modellzugriffe, Sitzungen, gemerkten Informationen und Sandboxes (Vorabversion).

Agentenidentitäten haben die Standardrollen roles/aiplatform.agentContextEditor und roles/aiplatform.agentDefaultAccess, damit Agenten grundlegende Berechtigungen für die Ausführung haben.

Sie können die Identität über die Agent Runtime-Konsole und ‑API aufrufen. Google Cloud

Hinweis: Wenn das Identitäts-Flag nicht konfiguriert ist, verwendet die Agent Runtime-Instanz weiterhin Dienstkonten. So wird die Abwärtskompatibilität gewährleistet, wenn Sie bereits Infrastructure-as-Code-basierte Bereitstellungen für Ihre Agenten implementiert haben.

Mit der Agent-Identität auf APIs und Dienste von Google Cloud zugreifen

Nachdem Sie einen KI-Agenten mit einer Agentenidentität erstellt haben, können Sie dem KI-Agenten mithilfe der folgenden IAM-Richtlinien Zugriff auf Google Cloud -APIs und ‑Dienste gewähren oder verweigern:

• Zulassungsrichtlinien: Gewähren einem Agenten Zugriff auf eine Google Cloud -Ressource.

• Ablehnungsrichtlinien: Einem Agenten den Zugriff auf eine Google Cloud -Ressource verweigern.

KI-Agenten Zugriff gewähren

Gewähren Sie der Agent-Identität IAM-Berechtigungen.

Hinweis: Standardmäßig werden bereitgestellten Agent-Identitäten die Rollen roles/aiplatform.agentDefaultAccess und roles/aiplatform.agentContextEditor zugewiesen. Diese bieten alle erforderlichen Berechtigungen für den Kernbetrieb, einschließlich der Ausführung von Inferenz (aiplatform.endpoints.predict), Sitzungen und Memory. Gewähren Sie Agent-Identitäten keine Rollen auf Projektebene wie roles/aiplatform.expressUser oder roles/aiplatform.user, da dies gegen das Prinzip der geringsten Berechtigung verstößt und es Agents ermöglicht, andere Agents im Projekt zu ändern oder zu löschen.

Wir empfehlen die folgenden Rollen:

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

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

• roles/secretmanager.secretAccessor: Gewährt dem Agent Zugriff auf Secrets im Secret Manager. Wenn Sie Secrets als Umgebungsvariablen referenzieren, müssen Sie dem Agent Platform-Dienst-Agent ([e-mail]) auch die Rolle roles/secretmanager.secretAccessor zuweisen, damit er die Secret-Werte während der Bereitstellung abrufen kann.

Wenn Sie Logging, Messwerte und die Cloud API-Registry verwenden, sind möglicherweise zusätzliche Berechtigungen erforderlich. Das gilt auch für alle anderen Ressourcen, die Sie für Ihren Agent freigeben möchten. Weitere Beispiele finden Sie 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:

• RESOURCE_TYPE: Der Ressourcentyp (z. B. projects oder organizations).

• RESOURCE_ID: Die ID der Ressource, für die Sie Zugriff gewähren möchten.

• ORGANIZATION_ID: Die ID für Ihre Organisation.

• PROJECT_NUMBER: Ihre Projektnummer.

• LOCATION: Ihre Region. Sehen Sie sich die unterstützten Regionen für Runtime an.

• AGENT_ENGINE_ID: Die Ressourcen-ID Ihrer Agent Runtime-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, verwenden die Standardanmeldedaten für Anwendungen des Agent Platform SDK automatisch die Agentenidentität, um die Authentifizierung beiGoogle Cloud -Ressourcen durchzuführen.

Zugriff für die Agent-to-Agent-Delegation (A2A) gewähren

Wenn Sie ein Multi-Agenten-System entwerfen, in dem ein übergeordneter Agent einen in der Agent Registry registrierten Remote-Subagenten aufruft, muss die Identität des übergeordneten Agenten Berechtigungen haben, um den Subagenten in der Agent Registry zu finden und seinen Endpunkt aufzurufen.

Damit die Identität des übergeordneten Agenten die erforderlichen Berechtigungen zum Erkennen und Aufrufen eines Remote-Sub-Agenten hat, bitten Sie Ihren Administrator, der Identität des übergeordneten Agenten die folgenden IAM-Rollen zuzuweisen:

Wichtig: Sie müssen diese Rollen der Identität des übergeordneten KI-Agenten und nicht Ihrem Nutzerkonto zuweisen. Wenn die Rollen nicht dem richtigen Hauptkonto zugewiesen werden, können Berechtigungsfehler auftreten.

• Lassen Sie den übergeordneten Agenten den Endpunkt des untergeordneten Agenten zur Laufzeit suchen: Agent Registry API Viewer (roles/agentregistry.viewer) für das übergeordnete Projekt oder die Registry-Ressource
• Dem übergeordneten Agenten erlauben, Nachrichten an den Sub-Agenten zu senden: Agent Platform User (roles/aiplatform.user) für die Reasoning-Engine-Ressource des Ziel-Sub-Agenten

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

Ihr Administrator kann der Identität des übergeordneten Agenten möglicherweise auch die erforderlichen Berechtigungen über benutzerdefinierte Rollen oder andere vordefinierte Rollen erteilen.

Wenn Sie beispielsweise die Rolle roles/agentregistry.viewer für das Projekt zuweisen möchten, können Sie den folgenden Google Cloud CLI-Befehl verwenden:

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/PARENT_AGENT_ENGINE_ID" \
    --role="roles/agentregistry.viewer"

Ersetzen Sie Folgendes:

• ORGANIZATION_ID: Die ID für Ihre Organisation.
• PROJECT_NUMBER: Ihre Projektnummer.
• LOCATION: Die Region, in der Ihr übergeordneter Agent bereitgestellt wird.
• PARENT_AGENT_ENGINE_ID: Die Ressourcen-ID der Agent Runtime-Instanz Ihres übergeordneten KI-Agenten.

Mehreren KI-Agenten Zugriff gewähren

Sie können allen Agent Runtime-Agenten in einem bestimmten Projekt oder in einer gesamten Organisation eine IAM-Rolle zuweisen.

Verwenden Sie einen der folgenden Befehle, um allen Agent Runtime-Agenten 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.proj-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

Es kann einfacher sein, allen KI-Agenten im Projekt allgemeine Berechtigungen wie Kontingente, Logging oder Zugriff auf Modelle zu gewähren, um Bereitstellungen zu vereinfachen. Gewähren Sie dann einzelnen KI-Agenten spezifische, eingeschränkte Berechtigungen für vertraulichere Berechtigungen wie den Zugriff auf Daten. Das Gewähren solcher Berechtigungen ist jederzeit nach der ersten Verwendung des Agentenidentitätsfeatures innerhalb einer Organisation oder eines Projekts möglich. Es kann also vor der Bereitstellung des Agenten erfolgen.

Mit den folgenden Befehlen werden beispielsweise allen Agents in einem Projekt einfache 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/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 Runtime-Agenten 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 für Agent-to-Agent-Aufrufe (A2A) gewähren

Wenn ein Agent (Agent A) einen anderen Agenten (Agent B) aufrufen muss, gewähren Sie keine projektweiten Berechtigungen. Weisen Sie stattdessen eine benutzerdefinierte Rolle zu, die nur aiplatform.reasoningEngines.query und aiplatform.reasoningEngines.get enthält und an den Ressourcenpfad von Agent B gebunden ist.

1. Erstellen Sie eine benutzerdefinierte Rolle agentInvoker mit den erforderlichen Berechtigungen:

   gcloud iam roles create agentInvoker --project=PROJECT_ID \
     --permissions=aiplatform.reasoningEngines.query,aiplatform.reasoningEngines.get \
     --stage=GA
   

2. Binden Sie die benutzerdefinierte Rolle an die Ressource von Agent B, um der Identität von Agent A Zugriff zu gewähren:

   gcloud beta ai reasoning-engines add-iam-policy-binding AGENT_B_ID \
     --region=LOCATION \
     --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_A_ID" \
     --role="projects/PROJECT_ID/roles/agentInvoker"
   

3. Wenn Sie verhindern möchten, dass Agentenidentitäten vertrauliche Verwaltungsvorgänge für andere Agenten ausführen, erstellen Sie eine IAM-Ablehnungsrichtlinie für reasoningEngines.create, .delete und .update:

   deniedPrincipals:
     - principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
   deniedPermissions:
     - aiplatform.googleapis.com/reasoningEngines.create
     - aiplatform.googleapis.com/reasoningEngines.delete
     - aiplatform.googleapis.com/reasoningEngines.update
   

Zugriff für einen KI-Agenten verweigern

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

• Verweigern Sie dem Agenten 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 zugreifen darf, unabhängig von anderen Berechtigungen, die der Agent möglicherweise 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
  

Anleitung zu CI/CD und Automatisierung

Bei automatisierten Bereitstellungspipelines, die Agents löschen und neu erstellen (z. B. Blau/Grün-Bereitstellungen, temporäre Testumgebungen oder Terraform-Workflows), kann es zu einem unbemerkten Verlust des Laufzeitzugriffs kommen. Da bei jeder erneuten Bereitstellung eine neue reasoningEngines-Ressource mit einer eindeutigen ID erstellt wird, erhält der Agent eine neue Hauptkonto-ID. Alle IAM-Berechtigungen, die dem vorherigen Hauptkonto gewährt wurden, werden nicht vom neuen Hauptkonto übernommen.

Verwenden Sie die folgenden Strategien, um Berechtigungen in automatisierten Pipelines zu verwalten:

• Neue Hauptkonto-ID dynamisch abrufen: Erfassen Sie den Wert spec.effectiveIdentity aus der Bereitstellungsantwort oder fragen Sie die REST API nach der Bereitstellung ab, um die aktive Identität des KI-Agenten zu erhalten. Wenden Sie die erforderlichen IAM-Bindungen auf dieses neue Hauptkonto als Schritt nach der Bereitstellung an.

  Sie können beispielsweise die aktive Identität mit gcloud mit dem folgenden Befehl abfragen:

  gcloud ai reasoning-engines describe RESOURCE_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format="value(spec.effectiveIdentity)"
  

  In Terraform können Sie das Hauptkonto der Agent-Identität dynamisch aus der bereitgestellten google_vertex_ai_reasoning_engine-Ressourcen-ID erstellen und in IAM-Bindungen darauf verweisen:

  resource "google_vertex_ai_reasoning_engine" "reasoning_engine" {
    provider = google-beta
  
    project      = var.project_id
    region       = var.region
    display_name = var.display_name
    description  = var.agent_description
  
    spec {
      agent_framework = "google-adk"
      identity_type   = "AGENT_IDENTITY"
  
      source_code_spec {
        inline_source {
          source_archive = filebase64(data.archive_file.agent_tarball.output_path)
        }
  
        python_spec {
          entrypoint_module = var.agent_python_spec.entrypoint_module
          entrypoint_object = var.agent_python_spec.entrypoint_object
          requirements_file = var.agent_python_spec.requirements_path
          version           = var.agent_python_spec.version
        }
      }
  
      deployment_spec {
        env {
          name  = "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY"
          value = "true"
        }
  
        env {
          name  = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
          value = "true"
        }
      }
    }
  }
  
  locals {
    agent_resource_id        = element(split("/", google_vertex_ai_reasoning_engine.reasoning_engine.id), -1)
    agent_identity_principal = "principal://agents.global.org-${data.google_organization.org.org_id}.system.id.goog/resources/aiplatform/projects/${data.google_project.project.number}/locations/${var.region}/reasoningEngines/${local.agent_resource_id}"
  }
  

• Verwenden Sie projektbezogene principalSets für grundlegende Berechtigungen: Da principalSet-Bindungen auf alle KI-Agenten in einem Projekt abzielen, bleiben sie auch nach dem Löschen und Neuerstellen von KI-Agenten erhalten. Weisen Sie dem projektweiten principalSet anstelle einzelner Agenten-Hauptkonten gängige, nicht vertrauliche Rollen (z. B. Dienstnutzung, Logging und allgemeine Modellinferenz) zu. Beschränken Sie einzelne principal://-Bindungen auf hochsensible Datenquellen.

Aktivitäten des Logging-Agenten protokollieren

Wenn Sie Cloud Logging aktivieren, können Sie Logs aufrufen, in denen aufgeführt ist, welcher KI-Agent und welche Nutzer auf eine Google Cloud -Ressource zugegriffen haben.

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

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

KI-Agenten und ihre Identitäten auflisten

Sie können die Liste Ihrer Agentenidentitäten in Agent Runtime über die Google Cloud Console und die Befehlszeile aufrufen.

Console

1. Rufen Sie in der Google Cloud Console die Seite Bereitstellungen der Agent-Plattform auf.
   

   Zu Deployments

   Bereitgestellte Agenten, 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 KI-Agenten wird die Identität in der Spalte Identität aufgeführt.

REST API

Sie können die Agentenidentität abrufen, wenn Sie eine Agent Runtime-Instanz über die REST API abrufen.

Die Antwort enthält die Agentenidentitä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 Runtime-Instanzen, die keine Agentenidentität verwenden, enthält das Feld effectiveIdentity den Namen des Dienst-Agenten oder Dienstkontos, der mit der Agent Runtime-Instanz verknüpft ist.

Kontextsensitiven Zugriff deaktivieren

Wenn Sie versuchen, ein Zugriffstoken außerhalb der vorgesehenen Agent Runtime-Laufzeit zu verwenden, wird standardmäßig der folgende Fehler ausgegeben:

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

In Ausnahmefällen, z. B. bei bestimmten Anforderungen an die Tokenfreigabe zwischen KI-Agenten, können Sie die Standard-CAA-Richtlinie deaktivieren. Von dieser Aktion wird dringend abgeraten, da der Agent dadurch anfällig für den Diebstahl von Anmeldedaten wird.

Sie können die Standardrichtlinie für den kontextsensitiven Zugriff deaktivieren, indem Sie beim Erstellen der Agent Runtime-Instanz die folgende Umgebungsvariable festlegen:

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

Nächste Schritte

Anleitung

Bereitgestellte KI-Agenten verwalten

Hier erfahren Sie, wie Sie KI-Agenten verwalten, die in der verwalteten Laufzeit der Agent Platform bereitgestellt wurden.

Anleitung

KI-Agenten verwenden

Agenten mit Agent Platform Runtime verwenden