Zur Agent Identity API migrieren

In diesem Dokument wird beschrieben, wie Sie Ihre bereitgestellten Agents und Authentifizierungsanbieter von der alten IAM Connectors API (iamconnectors.googleapis.com) zur neuen Agent Identity API (agentidentity.googleapis.com) migrieren.

Beide APIs sind während des Migrationszeitraums für die Vorschauversion parallel verfügbar. So können Sie Ihre Arbeitslasten migrieren, ohne bestehende Agent-Unterhaltungen zu unterbrechen.

Der Migrationsworkflow umfasst die folgenden Aufgaben:

  1. Agent Identity API aktivieren
  2. IAM-Zulassungsrichtlinien aktualisieren
  3. Agent-Code und SDKs aktualisieren
  4. Legacy-API deaktivieren

Agent Identity API aktivieren

Aktivieren Sie die neue Agent Identity API in Ihrem Projekt, um die Migration zu starten.

Aktivieren Sie die Agent Identity 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

API aktivieren

Wenn Sie die Agent Identity API aktivieren, wird auf der Seite „Agent Registry“ in derGoogle Cloud Console die neue API zum Lesen und Schreiben von Ressourcen verwendet:

  • Sie müssen Ihre Authentifizierungsanbieter nicht neu erstellen. Die neue API spiegelt jeden alten Authentifizierungsanbieter (z. B. projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME) als authProviders-Ressource (projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME) wider.

  • Ein neu erstellter Authentifizierungsanbieter, der die Google Cloud Console oder die gcloud CLI verwendet, wird als authProviders/-Ressource angezeigt und ist in der Legacy-API nicht sichtbar.

  • Die aktiven Kundenservicemitarbeiter, die die alten connectors/-Strings verwenden, können während des Migrationszeitraums weiterarbeiten.

IAM-Zulassungsrichtlinien aktualisieren

Weisen Sie den gespiegelten Ressourcen des Authentifizierungsanbieters die neuen IAM-Rollen zu, damit Ihre Agents Anmeldedaten von den neuen API-Endpunkten abrufen können.

Wenn Sie beispielsweise der SPIFFE-ID Ihres Agents die Rolle Connector User (roles/iamconnectors.user) für die alte Ressource connectors/AUTH_PROVIDER_NAME zugewiesen haben, weisen Sie der neuen Ressource authProviders/AUTH_PROVIDER_NAME die Rolle Agent Identity User (roles/agentidentity.user) zu:

gcloud alpha agent-identity authProviders add-iam-policy-binding \
    AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

Wenn Sie Ihren Agenten lokal mit adk web testen, gewähren Sie Ihrem privaten Nutzerkonto (user:USER_EMAIL) die Berechtigung roles/agentidentity.user.

Agentencode und SDKs aktualisieren

Aktualisieren Sie den Agent-Code, damit er auf die neue authProviders/-Ressourcenhierarchie und die neuen Endpunkte verweist:

  1. Aktualisieren Sie die ADK-Version in Ihrem Agent-Code auf 2.3.0 oder höher.

  2. Ersetzen Sie im Agent-Code (z. B. agent.py) connectors/ durch authProviders/ im Ressourcenstring GcpAuthProviderScheme.

    Alte Konfiguration: 

    auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME"
)

    Neue Konfiguration: 

    auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

  3. Nur dreibeiniges OAuth: Wenn Ihr Agent die REST API direkt aufruft, aktualisieren Sie den Endpunkthostnamen von iamconnectorcredentials.googleapis.com zu agentidentitycredentials.googleapis.com und ersetzen Sie connectors/ im Anfragepfad durch authProviders/.

  4. Nur dreibeiniges OAuth: Aktualisieren Sie auf Ihrem Frontend-Validierungsserver (z. B. main.py) die Endpunkt-URL FinalizeCredentials zu https://agentidentitycredentials.googleapis.com/v1alpha. Lesen Sie außerdem das auth_provider_name aus der eingehenden Anfrage und legen Sie es als Feld auth_provider im Anfragetext von FinalizeCredentials fest.

Legacy-API deaktivieren

Nachdem Sie Ihre IAM-Allow-Richtlinien aktualisiert und Ihren Agent-Code bereitgestellt haben, prüfen Sie, ob Ihr Agent Anmeldedaten mit der neuen API authentifiziert und abruft.

Nachdem Sie alle aktiven Workflows migriert haben, deaktivieren Sie den Legacy-Dienst in Ihrem Projekt:

gcloud services disable iamconnectors.googleapis.com \
    --project="PROJECT_ID"

Nächste Schritte