Zur Agent Identity API migrieren

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

Beide APIs werden während des Migrationszeitraums der Vorschauversion parallel betrieben, sodass Sie Ihre Arbeitslasten migrieren können, 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.

Agent Identity API aktivieren

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, wechselt die Seite „Agent-Registrierung“ in der Google Cloud Console zur neuen API, um Ressourcen zu lesen und zu schreiben:

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

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

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

IAM-Zulassungsrichtlinien aktualisieren

Weisen Sie die neuen IAM-Rollen für gespiegelte Authentifizierungsanbieter-Ressourcen zu, damit Ihre Agents Anmeldedaten von den neuen API-Endpunkten abrufen können.

Wenn Sie beispielsweise die Rolle Connector-Nutzer (roles/iamconnectors.user) der SPIFFE-ID Ihres Agents für die Legacy connectors/AUTH_PROVIDER_NAME Ressource zugewiesen haben, weisen Sie die Rolle Agent Identity-Nutzer (roles/agentidentity.user) für die neue authProviders/AUTH_PROVIDER_NAME Ressource 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 Agent lokal mit adk web testen, weisen Sie Ihrem persönlichen Nutzerkonto (user:USER_EMAIL) roles/agentidentity.user zu.

Agent-Code und SDKs aktualisieren

Aktualisieren Sie Ihren Agent-Code, um auf die neue authProviders/-Ressourcenhierarchie und die neuen Endpunkte zu verweisen:

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

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

    Legacy-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/ durch authProviders/ im Anfragepfad.

  4. Nur dreibeiniges OAuth: Aktualisieren Sie auf Ihrem Frontend-Validierungsserver (z. B. main.py) die Endpunkt-URL von FinalizeCredentials 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 Anfragetext von FinalizeCredentials fest.

Legacy-API deaktivieren

Nachdem Sie Ihre IAM-Zulassungsrichtlinien aktualisiert und Ihren Agent-Code bereitgestellt haben, prüfen Sie, ob sich Ihr Agent authentifiziert und Anmeldedaten mit der neuen API 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