KI-Agentenidentität mit Agent Runtime verwenden

Die Verwendung der Agentenidentität in der Agent Runtime bietet eine sichere, agentenspezifische Identität, die einen Ansatz der geringsten Berechtigung für die Zugriffsverwaltung ermöglicht. In diesem Dokument wird beschrieben, wie Sie Agents mit Agent-Identitä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 minimalen Berechtigungen ermöglicht und an den Lebenszyklus des Agents gebunden ist. Dadurch ist die Agentenidentität ein sichereres Hauptkonto als Dienstkonten. Vorhandene Zugriffsverwaltungsfunktionen über die IAM-Support-Agent-Identität ermöglichen eine starke Governance.

Die Anmeldedaten für die Agentenidentitä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 zertifikatgebundenen Tokens nur in der vorgesehenen, vertrauenswürdigen Laufzeitumgebung (z. B. einem Cloud Run-Container) verwendet werden können. Durch diese Sicherheitsbaseline können gestohlene Anmeldedaten nicht wiedergegeben werden, was vor Credential Theft und Kontoübernahmen (Account Takeover, ATO) schützt.

Auf dieser Seite werden die folgenden Themen behandelt:

Beschrä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.

Agent mit Agent-Identität erstellen

Sie können Agenten, die Sie in der Laufzeit für KI-Agenten bereitstellen, beim Erstellen Ihrer Agent Runtime-Instanz mit einer eindeutigen Identität versehen. Die Identität ist an die Agent-Ressourcen-ID der Agent Runtime 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 Runtime-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 Runtime-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={
    "display_name": "identity-for-agent",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
  },
)

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

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

    Definieren Sie den Agenten 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 sie dann bereit:

    import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Agent Platform 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}")

    BUCKET_NAME ist dabei der Name Ihres Cloud Storage-Buckets.

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

    agents-cli deploy --agent-identity

  • KI-Agenten mit Agent Identity mit ADK bereitstellen: KI-Agenten mit 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 Prinzipal-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 Agentenidentitä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 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 Identität von KI-Agenten basiert auf SPIFFE. Außerdem stellen wir automatisch ein x509-Zertifikat für den Agenten mit derselben Identität für die sichere Authentifizierung bereit und verwalten es. Standardmäßig erhält der Agent Zugriff auf seine eigenen Logs, Messwerte, den Modellzugriff, Sitzungen, Erinnerungen und Sandboxes (Vorabversion).

Agent-Identitäten haben standardmäßig die Rollen roles/aiplatform.agentContextEditor und roles/aiplatform.agentDefaultAccess, damit Agenten grundlegende Berechtigungen für die Ausführung von Vorgängen haben.

Sie können die Identität über die Agent Runtime Google Cloud Console und API anzeigen.

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 KI-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: Gewähren Sie dem Agent die Berechtigung, das Kontingent des Projekts und das Agent Platform SDK zu verwenden.

  • roles/browser: Zugriff auf grundlegende Google Cloud Funktionen gewähren.

Wenn Sie Logging, Messwerte und die Cloud API-Registrierung verwenden, sind möglicherweise zusätzliche Berechtigungen erforderlich. Das gilt auch für alle anderen Ressourcen, die Sie für Ihren Agenten verfügbar machen 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. Unterstützte Regionen für Runtime

  • 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, werden die Standardanmeldedaten für Anwendungen des Agent Platform SDK automatisch verwendet, um die Authentifizierung fürGoogle Cloud -Ressourcen mit der Identität des Agents durchzuführen.

Zugriff auf mehrere KI-Agenten gewähren

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

Verwenden Sie einen der folgenden Befehle, um allen Agent Runtime-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 Kontingent, Logging oder Zugriff auf Modelle zu gewähren, um die Bereitstellung zu vereinfachen. Gewähren Sie dann einzelnen Agenten bestimmte eingeschränkte Berechtigungen für sensiblere Berechtigungen wie den Zugriff auf Daten. Das Gewähren solcher Berechtigungen ist jederzeit nach der ersten Verwendung der Funktion für die Identität von Agents in einer Organisation oder einem Projekt möglich. Es kann 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 Runtime-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 KI‑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 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 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

Agent-Aktivitäten protokollieren

Wenn Sie Cloud Logging aktivieren, können Sie Logs dazu aufrufen, 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 eigenverantwortlich handelt, wird in den Protokollen nur die Identität des Agents angezeigt.

KI-Agenten und ihre Identitäten auflisten

Sie können die Liste Ihrer Agent-Identitäten in der 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 Agents, die Teil des ausgewählten Projekts sind, werden in der Liste angezeigt. Mit dem Feld Filter können Sie die Liste nach der von Ihnen angegebenen Spalte filtern.

  2. Die Identität des KI-Agents wird für jeden KI-Agent 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 Runtime-Instanz 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 Agent-Identität verwenden, enthält das Feld effectiveIdentity den Namen des Dienst-Agents oder Dienstkontos, der bzw. das 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 Sonderfällen, z. B. bei bestimmten Anforderungen für die gemeinsame Nutzung von Tokens zwischen Agents, können Sie die Standardrichtlinie für den kontextsensitiven Zugriff deaktivieren. Von dieser Aktion wird dringend abgeraten, da sie einen Agenten anfällig für den Diebstahl von Anmeldedaten macht.

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

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

Nächste Schritte

Leitfaden

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

Leitfaden

Einen Agent mit Agent Platform Runtime verwenden