Zur Agent Identity API migrieren

Sie können Ihre bereitgestellten KI-Agenten und Authentifizierungsanbieter von der Legacy-IAM Connectors API (iamconnectors.googleapis.com) zur Agent Identity API (agentidentity.googleapis.com) migrieren. Beide APIs funktionieren während des Migrationszeitraums der Vorabversion parallel, sodass Sie Ihre Arbeitslasten ohne Unterbrechung bestehender KI-Agenten-Unterhaltungen umstellen können.

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 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 derGoogle Cloud -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 Google Cloud 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 die alten connectors/-Strings verwenden, funktionieren während des Migrationszeitraums weiterhin.

IAM-Zulassungsrichtlinien aktualisieren

Gewähren Sie die neuen IAM-Rollen für gespiegelte Authentifizierungsanbieter-Ressourcen, 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, weisen Sie Ihrem persönlichen Nutzerkonto (user:USER_EMAIL) die Rolle roles/agentidentity.user zu.

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) im Ressourcenstring GcpAuthProviderScheme den Wert connectors/ durch authProviders/.

    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 im Anfragepfad connectors/ 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