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 werden während der Migrationsphase der Vorabversion parallel ausgeführt. 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.

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 Inhaberrolle (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 Registry“ in derCloud de Confiance -Konsole zur neuen API, um Ressourcen zu lesen und zu schreiben:

  • 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 Authentifizierungsanbieter, den Sie mit der Cloud de Confiance Console, der gcloud CLI oder der REST API erstellen, 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

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

Wenn Sie beispielsweise der SPIFFE-ID Ihres Agents für die Legacy-Ressource connectors/AUTH_PROVIDER_NAME die Rolle Connector User (roles/iamconnectors.user) zugewiesen haben, weisen Sie der neuen Ressource authProviders/AUTH_PROVIDER_NAME die Rolle Agent Identity User (roles/agentidentity.user) 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 Berechtigung roles/agentidentity.user.

Agentencode und SDKs aktualisieren

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

  1. Aktualisieren Sie die ADK-Version in Ihrem KI-Agenten-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 Hostnamen des Endpunkts von iamconnectorcredentials.googleapis.com auf 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 auf 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 sich Ihr Agent authentifiziert und Anmeldedaten über die neue 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