Zur Agent Identity API migrieren

In diesem Dokument wird beschrieben, wie Sie Ihre bereitgestellten Agents und Auth-Anbieter 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, falls sie noch nicht aktiviert ist.

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 -Konsole oder die gcloud CLI verwendet, wird als authProviders/-Ressource angezeigt und ist in der Legacy-API nicht sichtbar.

  • Die aktiven Agents, die die alten connectors/-Strings verwenden, funktionieren während des Migrationszeitraums weiterhin.

IAM-Zulassungsrichtlinien aktualisieren

Gewähren Sie die neuen IAM-Rollen für gespiegelte Ressourcen des Authentifizierungsanbieters, damit Ihre Agents Anmeldedaten von den neuen API-Endpunkten abrufen können.

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

gcloud agent-identity auth-providers 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 persönlichen Nutzerkonto (user:USER_EMAIL) die Rolle roles/agentidentity.user.

Agentencode und SDKs aktualisieren

Aktualisieren Sie Ihren 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 Hostnamen des Endpunkts 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 FinalizeCredentials-Endpunkt-URL zu https://agentidentitycredentials.googleapis.com/v1. Lesen Sie außerdem die auth_provider_name aus der eingehenden Anfrage und legen Sie sie als Feld auth_provider im FinalizeCredentials-Anfragetext fest.

Legacy-API deaktivieren

Nachdem Sie Ihre IAM-Zulassungsrichtlinien aktualisiert und Ihren Agent-Code bereitgestellt haben, prüfen Sie, ob Ihr Agent sich authentifiziert und Anmeldedaten über die neue API abruft.

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

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

Nächste Schritte