KI-Agentenidentität mit Agent Runtime verwenden

Die Verwendung der Agent-Identität in der Laufzeit für KI-Agenten bietet eine sichere, agentspezifische Identität, die einen Ansatz der geringsten Berechtigung für die Zugriffsverwaltung ermöglicht. In diesem Dokument wird erläutert, wie Sie Agenten mit Agent-Identitäten erstellen, den Zugriff auf Google Cloud APIs autorisieren und Anmeldedaten für Drittanbieterdienste verwalten.

Übersicht

Die Agent-Identität bietet eine agentspezifische Identität, die einen Ansatz der geringsten Berechtigung ermöglicht und an den Lebenszyklus des Agenten gebunden ist. Dadurch ist die Agent-Identität ein sichereres Hauptkonto als Dienstkonten. Vorhandene Zugriffsverwaltungskontrollen ü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 Agenten in Form von zertifikatgebundenen 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übernahmeangriffen (Account Takeover, ATO).

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 Laufzeitinstanz für KI-Agenten eine eindeutige Identität zuweisen. Die Identität ist an die Agent-Ressourcen-ID der Laufzeit für KI-Agenten gebunden und unabhängig vom Agent-Framework, das Sie zum Entwickeln des Agenten verwendet haben.

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

  • Laufzeitinstanz für KI-Agenten erstellen, ohne Agent-Code bereitzustellen: Wenn Sie IAM-Richtlinien einrichten möchten, bevor Sie den Agenten bereitstellen, können Sie eine Agent-Identität erstellen, ohne den Agent-Code bereitzustellen. Erstellen Sie dazu eine Laufzeitinstanz für KI-Agenten 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 Laufzeitinstanz für KI-Agenten mit der Agent-Identität erstellt haben, können Sie mit agent_engine.update(...)Agent-Code hinzufügen.

  • Laufzeitinstanz für KI-Agenten erstellen und gleichzeitig Agent-Code bereitstellen: 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 identity_type=AGENT_IDENTITY Flag.

    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 ihn 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}")

    Dabei ist BUCKET_NAME der Name Ihres Cloud Storage-Bucket.

  • 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 das Monitoring bietet. Mit dem folgenden Befehl wird Ihr Agent bereitgestellt:

    agents-cli deploy --agent-identity

  • Agenten mit Agent-Identität mit `adk deploy` bereitstellen: Richten Sie Ihren Agenten mit dem ADK ein. Bevor Sie adk deploy ausführen, führen Sie die folgenden Befehle im Ordner Ihres Agenten 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 Laufzeitinstanz für KI-Agenten 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 Agent Platform 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 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 für die sichere Authentifizierung bereit und verwalten es. Standardmäßig hat der Agent Zugriff auf seine eigenen Logs, Messwerte, den Modellzugriff, Sitzungen, Speicher und Sandboxes (Vorabversion).

Agent-Identitäten werden mit den Standardrollen roles/aiplatform.agentContextEditor und roles/aiplatform.agentDefaultAccess bereitgestellt, damit Agenten grundlegende Berechtigungen haben.

Sie können die Identität über die Console und API der Laufzeit für KI-Agenten aufrufen. Google Cloud

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

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

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

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

Zugriff auf einen Agenten gewähren

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

  • roles/aiplatform.expressUser: Gewährt Zugriff auf die Ausführung von Inferenz, Sitzungen und Speicher.

  • 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.

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 Agenten zur Verfügung stellen möchten. Weitere Beispiele finden Sie weiter unten.

Erstellen Sie eine IAM-Zulassungsrichtlinie, um einem Agenten 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 Ihrer Organisation.

  • PROJECT_NUMBER: Ihre Projektnummer.

  • LOCATION: Ihre Region. Informationen zu den unterstützten Regionen für die Laufzeit.

  • AGENT_ENGINE_ID: Die Ressourcen-ID Ihrer Laufzeitinstanz für KI-Agenten.

  • 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 die Agent-Identität verwenden, um die Authentifizierung bei Ressourcen durchzuführen.Google Cloud

Zugriff auf mehrere Agenten gewähren

Sie können allen Agenten der Laufzeit für KI-Agenten in einem bestimmten Projekt oder in der gesamten Organisation eine IAM-Rolle zuweisen.

Verwenden Sie einen der folgenden Befehle, um allen Agenten der Laufzeit für KI-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.project-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

Es kann einfacher sein, allen Agenten im Projekt allgemeine Berechtigungen wie Kontingent, Logging oder Zugriff auf Modelle zu gewähren, um Bereitstellungen zu vereinfachen. Weisen Sie dann einzelnen Agenten spezifische, eingeschränkte Berechtigungen für sensiblere Berechtigungen wie den Zugriff auf Daten zu. 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 Agenten erfolgen.

Mit den folgenden Befehlen werden beispielsweise allen Agenten 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-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 auf einen Agenten verweigern

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

  • Verweigern Sie dem Agenten 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 Hauptkonten ein, um die Ressourcen einzuschränken, auf die der Agent trotz anderer Berechtigungen 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ät protokollieren

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

Agenten und ihre Identitäten auflisten

Sie können die Liste Ihrer Agent-Identitäten in der Laufzeit für KI-Agenten über die Google Cloud Console und die Befehlszeile aufrufen.

Console

  1. Rufen Sie in der Google Cloud Console die Seite Bereitstellungen der Agent Platform 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 Agenten 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 Laufzeitinstanz für KI-Agenten mit der REST API abrufen.

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 Laufzeitinstanzen für KI-Agenten, die keine Agent-Identität verwenden, enthält das Feld effectiveIdentity den Namen des Dienst-Agenten oder Dienstkontos, der bzw. das mit der Laufzeitinstanz für KI-Agenten verknüpft ist.

Kontextsensitiven Zugriff deaktivieren

Wenn Sie versuchen, ein Zugriffstoken außerhalb der beabsichtigten Laufzeit für KI-Agenten 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 an die Tokenfreigabe zwischen Agenten, können Sie die Standardrichtlinie für den kontextsensitiven Zugriff deaktivieren. Von dieser Maßnahme wird dringend abgeraten, da ein Agent dadurch anfällig für Anmeldedatendiebstahl wird.

Deaktivieren Sie die Standardrichtlinie für den kontextsensitiven Zugriff, indem Sie beim Erstellen Ihrer Laufzeitinstanz für KI-Agenten die folgende Umgebungs variable festlegen :

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

Nächste Schritte

Leitfaden

Informationen zum Verwalten von Agenten, die in der verwalteten Laufzeit der Agent Platform bereitgestellt wurden.

Leitfaden

Verwenden Sie einen Agenten mit der Agent Platform Runtime.