Agent Platform-Funktionen für Cloud Run konfigurieren

Die Gemini Enterprise Agent Platform bietet Funktionen wie Agent Identity und Agent Registry, die integrierte Funktionen zum Erstellen, Bereitstellen und Verwalten von KI-Agenten, MCP-Servern (Model Context Protocol) und Tools bieten. 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 erfahren Sie, wie Sie:

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. Installieren Sie die Google Cloud CLI.

  5. Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

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

    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. Installieren Sie die Google Cloud CLI.

  10. Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

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

    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.

    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

  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. Die Preise für CPU, Arbeitsspeicher und ausgehenden Netzwerktraffic 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 das Projekt zuzuweisen, damit Sie die nötigen Berechtigungen für die Konfiguration von Agent Platform-Funktionen haben:

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 den Workload als KI-Agent. Für Arbeitslasten dieses Typs muss der Typ agent-identity verwendet werden.
    • mcp-server: kennzeichnet den Arbeitslast 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 Standard-Google Cloud-Dienstkonto.

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 --functional-type=agent und --identity-type=agent-identity an, um einen Agent-Job zu erstellen:

    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 Agent Identity auf, beschreiben Sie die Version Ihres Dienstes:

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 Agent-Identitä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 werden 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