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 systemverwaltete Identitäten und die automatische Registrierung nutzen, um die Ermittlung und Sicherheit Ihrer agentenbasierten Arbeitslasten zu vereinfachen.

In diesem Leitfaden wird Folgendes beschrieben:

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

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

Hinweis

  1. Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

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

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

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

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

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

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

  12. Aktivieren Sie die Cloud Run Admin API, die Identity and Access Management API, die Agent Registry API und die App Hub API, falls sie noch nicht aktiviert sind.

    Erforderliche Rollen zum Aktivieren von APIs

    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

  13. Richten Sie die Agent Registry in Ihrem Projekt oder Ihrer Organisation ein.
  14. Installieren und initialisieren Sie die gcloud CLI.
  15. Aktualisieren Sie die Komponenten:
    gcloud components update
  16. Informationen zu den Preisen für CPU, Arbeitsspeicher und ausgehenden Traffic finden Sie auf der Preisseite für Cloud Run. Die gesamte Größ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, vom System verwalteten Identität, die an seinen Lebenszyklus gebunden ist.
  • Aktivieren Sie die automatische Erkennung von KI-Agenten und MCP-Servern in der Agent Registry Ihrer Organisation.
  • Identity-Aware Proxy als Authentifizierungsrichtlinie zum Sichern von MCP-Servern verwenden

Funktions- und Identitätstypen verstehen

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

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

  • Funktionstyp: Gibt den primären Zweck der Arbeitslast an. Wenn diese Eigenschaft festgelegt ist, kann sie nicht mehr geändert oder entfernt werden. Sie weisen Ihrer Arbeitslast einen der folgenden funktionalen Typen zu:
    • agent: Kennzeichnet die Arbeitslast als KI-Agent. Arbeitslasten dieses Typs müssen den Typ agent-identity verwenden.
    • mcp-server: kennzeichnet den Workload als nutzerverwalteten MCP-Server. Für diesen Typ kann jeder unterstützte Identitätstyp verwendet werden.
  • Identitätstyp: Gibt die Art der Identität an, die der Arbeitslast zugewiesen ist. Wenn diese Eigenschaft festgelegt ist, kann sie nicht mehr geändert oder entfernt werden. Sie weisen Ihrer Arbeitslast einen der folgenden Identitätstypen zu:
    • agent-identity: weist eine vom System verwaltete Agentenidentität zu, die für Agents entwickelt wurde. Wenn Sie mit agent-identity bereitstellen, werden Identitätszertifikate auf der Agent Platform standardmäßig aktiviert. Wenn Sie die Funktion deaktivieren möchten, aktualisieren Sie Ihren Dienst mit dem Flag --no-identity-certificate oder legen Sie die Annotation run.googleapis.com/identity-certificate-enabled: "false" fest. Folgen Sie der Anleitung zum Authentifizieren von Tools und Ressourcen für Agents, die in eigener Verantwortung oder im Namen von Endnutzern handeln. Weitere Informationen zur Agent-Identität
    • service-account: verwendet ein Google Cloud-Standarddienstkonto.

Konfigurationsverhalten

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

Funktionstyp Identitätstyp Ergebnis
agent agent-identity Die Arbeitslast ist als Agent in der Agent Registry registriert und ihr ist eine vom System verwaltete Agent-Identität zugewiesen.
agent Sonstiges oder nicht angegeben Fehler. Für Arbeitslasten mit functional-type=agent muss identity-type=agent-identity verwendet werden.
mcp-server agent-identity, service-account oder nicht angegeben Die Arbeitslast ist 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 Standard-Cloud Run-Dienst oder -Job 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 --functional-type=agent und --identity-type=agent-identity an, um einen Agent bereitzustellen:

    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 verwenden, muss das Repository REPO_NAME bereits erstellt sein. Die URL hat das Format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

  • So aktualisieren Sie einen vorhandenen Dienst, damit er die Agent-Identität verwendet:

    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 Projektnummer.
    • REGION: die Region, in der Ihr Dienst bereitgestellt wird.

  • Wenn Sie einen vom Nutzer verwalteten MCP-Server bereitstellen möchten, geben Sie --functional-type=mcp-server an. Optional können Sie mit --identity-type einen Identitätstyp 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 verwenden, muss das Repository REPO_NAME 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 Agent-Jobs --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 Agent-Identität in der Google Cloud -Konsole oder mit der gcloud CLI aufrufen.

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 die Registerkarte Sicherheit.

Im Feld Identität wird die zugewiesene Agent-Identität angezeigt.

gcloud

So rufen Sie die Identität des Kundenservicemitarbeiters auf:

gcloud beta run revisions describe REVISION_NAME

Ersetzen Sie REVISION_NAME durch den Namen Ihrer Dienstversion.

Die zugewiesene Agent-Identitä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

So rufen Sie die Agentenidentität für eine Jobausführung auf:

gcloud beta run jobs executions describe EXECUTION_NAME

Ersetzen Sie EXECUTION_NAME durch den Namen der Jobausführung.

Die zugewiesene Agent-Identität wird in der Ausgabe angezeigt.

KI-Agent oder MCP in 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.

  • KI-Agenten werden im Agent-Katalog (/agents) registriert.
  • MCP-Server sind im MCP-Serverkatalog (/mcpServers) registriert.

Informationen dazu, wie Sie Ihre registrierten Agenten und Tools in der Registry aufrufen und wie Sie Ihre Agenten und Tools sicher speichern und finden, finden Sie unter Agent Registry.

Nächste Schritte