Zu einem neuen Modell migrieren

In diesem Dokument wird beschrieben, wie Sie eine vorhandene CX Agent Studio-Agentenanwendung zu einem anderen Foundation Model migrieren, die Qualität des Agenten validieren und die aktualisierte Konfiguration schrittweise bereitstellen, ohne den Live-Produktionstraffic zu unterbrechen.

Übersicht über den Migrationsworkflow

Eine vollständige Modellmigration umfasst vier Phasen:

1. Änderungen isolieren: Erstellen Sie eine unveränderliche Version Ihrer Produktions-Agent-Anwendung oder exportieren und importieren Sie die Anwendung in eine separate Testumgebung.
2. Modelleinstellungen aktualisieren: Ändern Sie das globale Modell, prüfen Sie die Überschreibungen für Sub-Agenten- und Tool-Modelle und überprüfen Sie die Einstellungen für Wiederholungsversuche und Fallbacks über die Console, exportierte Konfigurationsdateien oder die REST API.
3. Leistung bewerten und optimieren: Testen Sie Unterhaltungen im Simulator, führen Sie Bewertungen mit Probleme mit KI finden durch und verwenden Sie AI Co-Builder: Arc, um Anweisungen zu optimieren, bis Ihre Qualitätsmesswerte die Zielschwellenwerte erreichen.
4. In Phasen bereitstellen: Speichern Sie die validierte Konfiguration als Version und verwenden Sie die Aufteilung des Traffics in Ihrem Bereitstellungskanal, um den Live-Traffic schrittweise zu verschieben, während Sie die Ergebnisse beobachten.

Schritt 1: Änderungen isolieren

Bevor Sie die Modelleinstellungen ändern, sollten Sie Ihre Arbeit isolieren, damit sich Aktualisierungen und Tests nicht auf Live-Kundenunterhaltungen auswirken. Sie können Änderungen entweder mithilfe von Versionen innerhalb derselben Agentenanwendung oder durch Exportieren der Anwendung in eine separate Sandbox-Umgebung isolieren.

Versionen in derselben Agentenanwendung verwenden

Wenn Ihre Bereitstellungskanäle auf eine bestimmte unveränderliche Version verweisen, wirken sich Änderungen, die Sie an der Entwurfsversion der Agent-Anwendung vornehmen, erst dann auf den Live-Traffic aus, wenn Sie eine Version erstellen und sie einem Bereitstellungskanal zuweisen.

So speichern Sie einen Referenz-Snapshot Ihrer aktuellen Konfiguration:

1. Öffnen Sie die CX Agent Studio-Konsole und wählen Sie Ihre Agent-Anwendung aus.
2. Öffnen Sie im Agent Builder den Bereich Versionen.
3. Klicken Sie auf + Version erstellen.
4. Geben Sie einen aussagekräftigen Namen wie pre-model-migration-baseline und optional eine Beschreibung ein und klicken Sie dann auf Erstellen.
5. Öffnen Sie den Tab Bereitstellen und prüfen Sie, ob Ihre aktiven Bereitstellungskanäle auf eine unveränderliche Version verweisen (gekennzeichnet durch ein Live-Badge im Bereich Versionen) und nicht auf den veränderlichen Entwurf.

In eine Sandbox-Umgebung exportieren und importieren

Wenn Sie Modelländerungen in einem separaten Projekt oder einer Staging-Anwendung testen möchten, exportieren Sie Ihre Agent-Anwendung und importieren Sie sie in Ihre Testumgebung:

1. Öffnen Sie die CX Agent Studio Console und wählen Sie Ihr Projekt aus.
2. Öffnen Sie in der Liste der Agent-Anwendungen das Menü für Ihre Anwendung und wählen Sie Exportieren aus.
3. Wenn Ihre Sandbox-Umgebung andere externe Abhängigkeiten wie Datenspeicher oder Dienstendpunkte verwendet, extrahieren Sie das heruntergeladene Archiv, aktualisieren Sie die Datei environment.json und komprimieren Sie das Verzeichnis in ein ZIP-Archiv. Weitere Informationen finden Sie unter Umgebungsdatei.
4. Öffnen Sie in Ihrem Sandbox-Projekt oder Ihrer Testanwendung das Anwendungsmenü, wählen Sie Importieren aus und laden Sie das Archiv hoch.
5. Optional: Exportieren Sie Ihre Testläufe aus der Quellanwendung und importieren Sie sie in die Sandbox-Anwendung, damit Sie Regressionstests ausführen können.

Schritt 2: Modelleinstellungen aktualisieren

Sehen Sie sich die Liste der unterstützten Modelle an, um ein Gemini-Zielmodell auszuwählen, das der Modalität Ihres KI-Agenten (Text oder Sprache) entspricht. Sie können Modelleinstellungen über die Console, exportierte Konfigurationsdateien oder die REST API aktualisieren.

Modelle mit der Console aktualisieren

Wenn Sie eine Agent-Anwendung in der Console migrieren, prüfen Sie das globale Anwendungsmodell, die einzelnen Agent-Überschreibungen, die Datenspeichertool-Modelle und die Fallback-Einstellungen:

1. Globales Modell ändern:
   1. Öffnen Sie im Agent Builder die Einstellungen, um die Einstellungen für die Agent-Anwendung aufzurufen.
   2. Wählen Sie unter Basic > Interactions im Feld Global model Ihr Zielmodell aus. Dieses Modell dient als Standard für alle Agenten in der Anwendung, für die keine Überschreibung angegeben ist.
2. Überschreibungen für Stamm- und Sub-Agenten-Modelle prüfen:
   1. Öffnen Sie im Agent Builder das Menü in der Titelleiste des Stamm-Agenten und wählen Sie Konfiguration bearbeiten aus, um die Agenteneinstellungen aufzurufen.
   2. Prüfen Sie das Feld Modell. Wenn der KI-Agent das globale Modell überschreibt, wählen Sie Ihr Zielmodell aus oder löschen Sie die Überschreibung, damit der KI-Agent das globale Modell übernimmt.
   3. Wiederholen Sie diese Prüfung für jeden Sub-Agenten in Ihrer Agentenhierarchie.
3. Modelle für Datenspeichertools prüfen:
   1. Wenn Ihre Anwendung Datenspeicher-Tools verwendet, öffnen Sie den Bereich Tools und wählen Sie jedes Datenspeicher-Tool aus.
   2. Maximieren Sie Erweitert > Modalitäten und prüfen Sie die Auswahl für Rewriter-Modell und Zusammenfassungsmodell für die Konfigurationen Text und Sprache.
4. Einstellungen für Wiederholungsversuche und Fallback prüfen:
   1. Öffnen Sie die Einstellungen für die Agent-Anwendung und gehen Sie zu Allgemein > Verhalten > Fallback-Verhalten.
   2. Prüfen Sie, ob Wiederholungsversuche, Agent-Antwort und Fallback für die Fehlerbehandlung während der Modellgenerierung richtig konfiguriert sind.

Hinweis: Wenn Sie einen Sprach-Agenten von gemini-composite-v1 zu gemini-composite-v2 migrieren, sollten Sie auch den Prompt für den Sprechstil überprüfen und Inline-Tags in eckigen Klammern in spitze Klammern umwandeln. Weitere Informationen finden Sie unter Von Composite V1 migrieren.

Modelle mit exportierten Konfigurationsdateien aktualisieren

Wenn Sie Ihre Agentenanwendung über die Versionsverwaltung oder CI/CD-Pipelines verwalten, können Sie die Modelleinstellungen im exportierten Archiv aktualisieren und das Paket noch einmal importieren:

1. Extrahieren Sie das ZIP-Archiv Ihrer exportierten Agentenanwendung.

2. Öffnen Sie für jedes Agentenverzeichnis unter agents/<var>AGENT_NAME</var>/ die Datei agents/<var>AGENT_NAME</var>/<var>AGENT_NAME</var>.yaml und aktualisieren Sie das Feld modelSettings.model mit der Zielmodell-ID:

   displayName: "AGENT_NAME"
   modelSettings:
     model: "MODEL_ID"
   instruction: "agents/AGENT_NAME/instruction.txt"
   

   Ersetzen Sie Folgendes:

   • <var>AGENT_NAME</var>: der Anzeigename des KI-Agenten.
   • <var>MODEL_ID</var>: die Kennung des Zielmodells, z. B. gemini-3.5-flash oder gemini-composite-v2.

3. Komprimieren Sie das Stammverzeichnis in ein ZIP-Archiv und importieren Sie das aktualisierte Archiv in CX Agent Studio.

Modelle mit der REST API aktualisieren

Sie können ModelSettings in Ihrer Agentenanwendung und für einzelne Agenten programmatisch über die CX Agent Studio REST API aktualisieren.

Ermitteln Sie vor dem Aufrufen der API die folgenden Werte:

• <var>PROJECT_ID</var>: Projekt-ID in Google Cloud .
• <var>LOCATION_ID</var>: die Region Ihrer Agentenanwendung, z. B. us oder eu.
• <var>APP_ID</var>: Die Ressourcen-ID Ihrer KI-Agentenanwendung.
• <var>AGENT_ID</var>: die Ressourcen-ID eines bestimmten Stamm- oder Sub-Agenten.
• <var>MODEL_ID</var>: die Zielmodell-ID, z. B. gemini-3.5-flash.

Wenn Sie das globale Standardmodell für die KI-Agentenanwendung aktualisieren möchten, senden Sie eine PATCH-Anfrage an die Methode projects.locations.apps.patch mit updateMask=modelSettings:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

Wenn Sie die Modellüberschreibung für einen einzelnen Root-Agenten oder Sub-Agenten aktualisieren möchten, senden Sie eine PATCH-Anfrage an die Methode projects.locations.apps.agents.patch mit updateMask=modelSettings:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID/agents/AGENT_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

Schritt 3: Leistung des KI-Agenten bewerten und optimieren

Foundation Models können sich in Bezug auf Reasoning-Stil, Befolgung von Anweisungen, Ausführlichkeit und Toolaufrufverhalten unterscheiden. Testen Sie Ihren Agenten nach dem Modellwechsel und optimieren Sie seine Anweisungen, bevor Sie Live-Kundentraffic an die aktualisierte Konfiguration weiterleiten.

Interaktiv im Simulator testen

Führen Sie im Simulator Agent-Vorschau erste Plausibilitätsprüfungen durch:

1. Öffnen Sie den Simulator im Agent Builder und klicken Sie auf Neue Unterhaltung starten.
2. Testen Sie repräsentative Text- oder Audiointeraktionen und prüfen Sie, ob der Agent die Anweisungen befolgt, Tools mit gültigen Argumenten aufruft und wie erwartet zwischen Sub-Agenten wechselt.
3. Maximieren Sie die Trace-Details für jede Runde, um die Schrittlatenz, die Tool-Ein- und -Ausgaben sowie die JSON-Rohantworten zu prüfen.
4. Optional: Wenn Sie Ihrer Regressionssuite eine Unterhaltung hinzufügen möchten, öffnen Sie das Simulatormenü und wählen Sie Als Golden speichern aus.

Bewertungen ausführen und Probleme mit KI diagnostizieren

Verwenden Sie Bewertungen, um die Leistung Ihrer Golden-, Szenario- und Simulationstestläufe zu messen und die Ergebnisse mit Ihrer Baseline-Version zu vergleichen:

1. Klicken Sie oben im Agent Builder auf Bewerten.
2. Wählen Sie die Testfälle aus, die Ihre Critical User Journeys und Agentenvarianten abdecken, und klicken Sie dann auf Ausgewählte ausführen.
3. Wählen Sie im Dialogfeld für die Ausführung die Option Probleme mit KI finden aus, legen Sie die Anzahl der Ausführungen für eine optimale KI-Analyse auf 3 oder mehr fest und starten Sie dann die Ausführung. Weitere Informationen finden Sie unter Testfälle mithilfe von KI verbessern.
4. Prüfen Sie nach Abschluss des Durchlaufs die Bewertungsmesswerte, einschließlich Tool-Korrektheit, semantische Übereinstimmung, Zufriedenheit mit dem Nutzerziel, Zielerreichung, Halluzinationen und Aufgabenerfüllung. Untersuchen Sie außerdem alle fehlgeschlagenen Durchgänge oder nicht erreichten Ziele.
5. Klicken Sie auf der Ergebnisseite auf Gemini fragen, um die generierte loss_report zu prüfen, die Ursachen für fehlgeschlagene Ausführungen zusammenzufassen und vorgeschlagene Korrekturen für Anweisungen oder Konfigurationen anzusehen.

Anleitung für Hill-Climbing mit AI Co-Builder: Arc

Wenn die Bewertungsergebnisse Regressionen oder Verhaltensänderungen im Zielmodell zeigen, verwenden Sie AI Co-Builder: Arc und den Bewertungshelfer, um Ihre Prompts iterativ zu verfeinern:

1. Klicken Sie oben im Agent Builder auf Arc, um den AI Co-Builder zu öffnen.
2. Klicken Sie auf Kontext auswählen und wählen Sie die spezifischen Agenten oder Anweisungen aus, die angepasst werden müssen, oder hängen Sie fehlgeschlagene Transkripte und Verlustberichte an.
3. Fordern Sie Arc auf, Ihre Anweisungen oder Toolbeschreibungen zu aktualisieren, um die beobachteten Fehler zu beheben, während das Verhalten in anderen Testfällen beibehalten wird. Sie können auch die Funktion Anweisungen umstrukturieren verwenden, um Anweisungen in einem strukturierten Format zu organisieren.
4. Führen Sie die Bewertungssuite nach dem Anwenden von Korrekturen noch einmal aus und wiederholen Sie den Vorgang, bis alle Testfälle die Kriterien erfüllen. Weitere Informationen finden Sie unter Best Practices für Bewertungen und Hillclimbing.

Schritt 4: Stufenweise Bereitstellung mit Aufteilung des Traffics

Sobald der aktualisierte Agent die Bewertungen besteht, können Sie ihn schrittweise mithilfe von Versionen und der Aufteilung des Traffics einführen.

Version für den migrierten Agenten erstellen

Speichern Sie einen unveränderlichen Snapshot Ihrer validierten Konfiguration:

1. Wenn Sie Änderungen in einer separaten Sandbox-Anwendung getestet haben, exportieren Sie das validierte Anwendungspaket und importieren Sie es in Ihre Produktionsanwendung.
2. Öffnen Sie in Ihrer Produktionsanwendung den Bereich Versionen und klicken Sie auf + Version erstellen.
3. Geben Sie einen Namen und eine Beschreibung ein, die das Zielmodell identifizieren, z. B. v2-gemini-3-5-flash, und klicken Sie dann auf Erstellen.

Live-Traffic schrittweise verlagern

Verwenden Sie die Aufteilung des Traffics, um einen kleinen Prozentsatz der Live-Unterhaltungen an die migrierte Version weiterzuleiten, bevor Sie sie auf 100 % des Traffics hochstufen:

1. Klicken Sie oben im Agent Builder auf den Tab Bereitstellen und wählen Sie den Bereitstellungskanal aus.
2. Klicken Sie unter Agent-Version auf Version hinzufügen und fügen Sie sowohl Ihre Baseline-Produktionsversion als auch Ihre migrierte Kandidatenversion hinzu.
3. Weisen Sie der Kandidatenversion einen kleinen anfänglichen Traffic-Prozentsatz zu (z. B. 90 % für die Baseline-Version und 10 % für die Kandidatenversion, insgesamt 100 %) und speichern Sie dann die Kanalkonfiguration. Sie können experimentConfig.versionRelease.trafficAllocations auch programmatisch mit der REST API konfigurieren.
4. Live-Leistung über Versionen hinweg beobachten:
   • Prüfen Sie das Sitzungsvolumen, die Latenz und die Eskalationsraten im Monitoring-Dashboard.
   • Prüfen Sie die Live-Transkripte im Unterhaltungsverlauf.
   • Fragen Sie exportierte Interaktionsprotokolle nach app_version_id in BigQuery ab, um die Ausführungs- und Ergebnisraten von Tools über verschiedene Versionen hinweg zu vergleichen. Beispiele für SQL-Abfragen finden Sie unter Versionsleistung in BigQuery analysieren.
5. Wenn Sie die Stabilität und Qualität bestätigt haben, erhöhen Sie den Traffic-Prozentsatz für die migrierte Version schrittweise, bis sie 100 % des Live-Traffics bereitstellt. Wenn Sie während des Roll-outs unerwartete Probleme feststellen, leiten Sie 100 % des Traffics zurück zur Baseline-Version oder stellen Sie die vorherige Version im Bereich Versionen wieder her.