Agent Platform-Funktionen für Cloud Run konfigurieren

Gemini Enterprise Agent Platform Funktionen wie Agent Identity und Agent Registry bieten integrierte Funktionen zum Erstellen, Bereitstellen und Verwalten von KI-Agenten, MCP-Servern (Model Context Protocol) und Tools. Wenn Sie diese Funktionen für Ihre Cloud Run-Ressourcen aktivieren, können Sie von systemverwalteten Identitäten und der automatischen Registrierung profitieren, um die Erkennung und Sicherheit für Ihre agentischen Arbeitslasten zu vereinfachen.

In dieser Anleitung erfahren Sie, wie Sie Folgendes tun:

Cloud Run unterstützt die folgenden Agent Platform-Funktionen:

  • Agent Identity: Weist Ihrer Arbeitslast eine eindeutige, kryptografisch überprüfbare Identität zu, die sichere Verbindungen zu anderen Agenten, Tools und Google Cloud APIs ermöglicht.
  • Agent Registry: Registriert Ihre Agenten und Tools automatisch, damit sie von anderen Entwicklern und Agenten in Ihrer Organisation gefunden werden können.

Hinweis

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Installieren Sie die Google Cloud CLI.

  4. Konfigurieren Sie die gcloud CLI für die Verwendung Ihrer föderierten Identität.

    Weitere Informationen finden Sie unter Mit Ihrer föderierten Identität in der gcloud CLI anmelden.

  5. Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init

  6. Aktivieren Sie die Cloud Run Admin API, die Identity and Access Management API, die Agent Registry API und die App Hub API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen.

    APIs aktivieren

  7. Achten Sie darauf, dass Sie die Agent Registry in Ihrem Projekt oder Ihrer Organisation eingerichtet haben.
  8. Installieren und initialisieren Sie die gcloud CLI.
  9. Aktualisieren Sie die Komponenten: 
    gcloud components update
  10. Informationen zu Preisen für CPU, Arbeitsspeicher und ausgehenden Netzwerktraffic finden Sie auf der Cloud Run Preisseite. Die Gesamtgröße des bereitgestellten Laufwerks und die Lebensdauer der Instanz, die es verwendet, tragen zu Ihren Kosten bei.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren von Agent Platform-Funktionen benötigen:

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

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Anwendungsfälle

Verwenden Sie Agent Platform-Funktionen mit Cloud Run in den folgenden Szenarien:

  • Authentifizieren Sie Ihren Agenten bei anderen Agenten, Tools und Google Cloud APIs mit einer eindeutigen, systemverwalteten Identität, die an seinen Lebenszyklus gebunden ist.
  • Aktivieren Sie die automatische Erkennung von Agenten und MCP-Servern in der Agent Registry Ihrer Organisation.
  • Verwenden Sie Identity-Aware Proxy als Authentifizierungsrichtlinie, um MCP-Server zu schützen.

Funktions- und Identitätstypen verstehen

Sie konfigurieren Agent Platform-Funktionen, indem Sie Funktions- und Identitätseigenschaften für Ihre Cloud Run-Ressourcen festlegen.

Diese beiden Eigenschaften steuern, wie eine Arbeitslast registriert und identifiziert wird:

  • Funktionstyp: Deklariert den primären Zweck der Arbeitslast. Nach dem Festlegen kann diese Eigenschaft nicht mehr geändert oder aufgehoben werden. Sie weisen Ihrer Arbeitslast einen der folgenden Funktionstypen zu:
    • agent: Gibt an, dass die Arbeitslast ein KI-Agent ist. Arbeitslasten dieses Typs müssen den Typ agent-identity verwenden.
    • mcp-server: Gibt an, dass die Arbeitslast ein vom Nutzer verwalteter MCP-Server ist. Dieser Typ kann jeden unterstützten Identitätstyp verwenden.
  • Identitätstyp: Gibt die Art der Identität an, die der Arbeitslast zugewiesen ist. Nach dem Festlegen kann diese Eigenschaft nicht mehr geändert oder aufgehoben werden. Sie weisen Ihrer Arbeitslast einen der folgenden Identitätstypen zu:
    • agent-identity: Weist eine systemverwaltete Agentenidentität zu, die für Agenten entwickelt wurde. Wenn Sie mit agent-identity bereitstellen, aktiviert die Agent Platform standardmäßig Identitätszertifikate. Wenn Sie diese Funktion deaktivieren möchten, aktualisieren Sie Ihren Dienst mit dem --no-identity-certificate Flag oder legen Sie die run.googleapis.com/identity-certificate-enabled: "false" Annotation fest. Folgen Sie der Anleitung, um sich bei Tools und Ressourcen für Agenten zu authentifizieren , die in eigener Verantwortung oder im Namen von Endnutzern handeln. Um die Kernkonzepte und Sicherheitsvorteile von systemverwalteten Agentenidentitäten zu verstehen, erfahren Sie mehr über Agent Identity.
    • service-account: Verwendet ein Standarddienstkonto von Google Cloud.

Konfigurationsverhalten

Das Verhalten von Funktions- und Identitätseigenschaften hängt von der gewählten Kombination ab:

Funktionstyp Identitätstyp Ergebnis
agent agent-identity Die Arbeitslast wird als Agent in der Agent Registry registriert und ihr wird eine systemverwaltete Agentenidentität zugewiesen.
agent Sonstiges oder nicht angegeben Fehler. Arbeitslasten mit functional-type=agent müssen identity-type=agent-identity verwenden.
mcp-server agent-identity, service-account oder nicht angegeben Die Arbeitslast wird als MCP-Server (/mcpServers) in der Agent Registry registriert. Wenn nicht angegeben, wird standardmäßig eine Dienstkontoidentität verwendet.
Ohne Angabe service-account Die Arbeitslast wird als Standarddienst oder ‑job von Cloud Run ausgeführt.

Funktionen für Dienste und Jobs konfigurieren

Sie konfigurieren Agent Platform-Funktionen für Ihre Cloud Run-Dienste und ‑Jobs mit der Google Cloud CLI.

Dienste

  • Geben Sie zum Bereitstellen eines Agenten --functional-type=agent und --identity-type=agent-identity an:

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=agent \
    --identity-type=agent-identity

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: der Name Ihres Cloud Run-Dienstes.
    • IMAGE_URL: ein Verweis auf das Container-Image, z. B. us-docker.pkg.dev/cloudrun/container/hello:latest. Wenn Sie Artifact Registry, das Repository REPO_NAME muss bereits erstellt sein. Die URL hat das Format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

  • So aktualisieren Sie einen vorhandenen Dienst, um die Agent Identity zu verwenden:

    gcloud beta run services update SERVICE_NAME \
    --functional-type=agent \
    --identity-type=agent-identity \
    --no-traffic

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: der Name Ihres Cloud Run-Dienstes.
    • ORGANIZATION_ID: Ihre Google Cloud Organisations-ID.
    • PROJECT_NUMBER: Ihre Google Cloud Projekt nummer.
    • REGION: die Region, in der Ihr Dienst bereitgestellt wird.

  • Geben Sie --functional-type=mcp-server an, um einen vom Nutzer verwalteten MCP-Server bereitzustellen. Sie können optional einen Identitätstyp mit --identity-type angeben:

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=mcp-server \
    --identity-type=IDENTITY_TYPE

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: der Name Ihres Cloud Run-Dienstes.
    • IMAGE_URL: ein Verweis auf das Container-Image, z. B. us-docker.pkg.dev/cloudrun/container/hello:latest. Wenn Sie Artifact Registry, das Repository REPO_NAME muss bereits erstellt sein. Die URL hat das Format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • IDENTITY_TYPE: Optional. Der Identitätstyp, der der Arbeitslast zugewiesen ist. Geben Sie agent-identity oder service-account an. Die Standardeinstellung ist service-account.

Jobs

  • Geben Sie zum Erstellen eines Agentenjobs --functional-type=agent und --identity-type=agent-identity an:

    gcloud beta run jobs create JOB_NAME \
  --image=IMAGE_URL \
  --functional-type=agent \
  --identity-type=agent-identity

    Ersetzen Sie Folgendes:

    • JOB_NAME: der Name Ihres Cloud Run-Jobs.
    • IMAGE_URL: ein Verweis auf das Container-Image.

Zugewiesene Identitäten ansehen

Sie können die zugewiesene Agentenidentität in der Google Cloud Console oder gcloud CLI ansehen.

Dienste

Console

  1. Rufen Sie in der Google Cloud Console Cloud Run auf:

    Zu Cloud Run

  2. Wählen Sie im Navigationsmenü von Cloud Run Dienste aus und klicken Sie auf Ihren Dienst.

  3. Klicken Sie auf den Tab Überarbeitungen und wählen Sie eine Überarbeitung aus.

  4. Klicken Sie auf den Tab Sicherheit.

Im Feld Identität wird die zugewiesene Agentenidentität angezeigt.

gcloud

Beschreiben Sie die Überarbeitung Ihres Dienstes, um die Agentenidentität anzusehen:

gcloud beta run revisions describe REVISION_NAME

Ersetzen Sie REVISION_NAME durch den Namen Ihrer Dienstüberarbeitung.

Die zugewiesene Agentenidentität wird in der Ausgabe angezeigt.

Jobs

Console

  1. Rufen Sie in der Google Cloud Console Cloud Run auf:

    Zu Cloud Run

  2. Wählen Sie im Navigationsmenü von Cloud Run Jobs aus und klicken Sie auf Ihren Job.

  3. Klicken Sie auf den Tab Ausführungen und wählen Sie eine Ausführung aus.

  4. Sehen Sie sich die Ausführungsdetails an.

Im Feld Identität wird die zugewiesene Agentenidentität angezeigt.

gcloud

Beschreiben Sie die Ausführung, um die Agentenidentität für eine Jobausführung anzusehen:

gcloud beta run jobs executions describe EXECUTION_NAME

Ersetzen Sie EXECUTION_NAME durch den Namen Ihrer Jobausführung.

Die zugewiesene Agentenidentität wird in der Ausgabe angezeigt.

Agent oder MCP in der Agent Registry ansehen

Wenn Sie eine Cloud Run-Ressource mit --functional-type=agent oder --functional-type=mcp-server bereitstellen, wird sie automatisch in der Agent Registry Ihrer Organisation registriert.

  • Agenten werden im Agentenkatalog (/agents) registriert.
  • MCP-Server werden im MCP-Server-Katalog (/mcpServers) registriert.

Weitere Informationen zum Ansehen Ihrer registrierten Agenten und Tools in der Registry sowie zum sicheren Speichern und Erkennen Ihrer Agenten und Tools finden Sie unter Agent Registry.

Nächste Schritte