Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

新しいモデルに移行する

このドキュメントでは、既存の CX Agent Studio エージェントアプリケーションを別の基盤モデルに移行し、エージェントの品質を検証して、ライブの本番環境トラフィックを中断することなく、更新された構成を段階的にデプロイする方法について説明します。

移行ワークフローの概要

モデルの移行は、次の 4 つのステージで構成されます。

変更を分離する: 本番環境のエージェントアプリケーションの不変のバージョンを作成するか、アプリケーションをエクスポートして別のテスト環境にインポートします。
モデル設定を更新する: コンソール、エクスポートされた構成ファイル、または REST API を使用して、グローバルモデルの変更、サブエージェントとツールモデルのオーバーライドの確認、再試行と代替の設定の確認を行います。
パフォーマンスを評価して改良する: シミュレータで会話をテストし、AI で問題を見つけるを使用して評価を実行します。AI Co-Builder: Arc を使用して、品質指標が目標のしきい値を満たすまで指示をチューニングします。
段階的にデプロイする: 検証済みの構成をバージョンとして保存し、デプロイチャンネルでトラフィック分割を使用して、結果をモニタリングしながらライブトラフィックを段階的に移行します。

ステップ 1: 変更を分離する

モデルの設定を変更する前に、更新やテストがお客様との実際の会話に影響しないように、作業を分離します。変更を分離するには、同じエージェントアプリケーション内でバージョンを使用するか、アプリケーションを別のサンドボックス環境にエクスポートします。

同じエージェントアプリケーションでバージョンを使用する

デプロイチャネルが特定の不変のバージョンを指している場合、ドラフトエージェントアプリケーションに加えた編集は、バージョンを作成してデプロイチャネルに割り当てるまで、ライブトラフィックに影響しません。

現在の構成のベースラインスナップショットを保存するには:

CX Agent Studio コンソールを開き、エージェントアプリケーションを選択します。
エージェントビルダーで [バージョン] ペインを開きます。
[+ バージョンを作成] をクリックします。
わかりやすい名前（pre-model-migration-baseline など）と説明（省略可）を入力し、[作成] をクリックします。
[Deploy] タブを開き、アクティブなデプロイチャネルが、変更可能なドラフトではなく、不変のバージョン（[Versions] ペインの [Live] バッジで示されます）を指していることを確認します。

サンドボックス環境へのエクスポートとインポート

別のプロジェクトまたはステージングアプリケーションでモデルの変更をテストする場合は、エージェントアプリケーションをエクスポートしてテスト環境にインポートします。

CX Agent Studio コンソールを開き、プロジェクトを選択します。
エージェントアプリケーションリストで、アプリケーションのメニューを開き、[エクスポート] を選択します。
サンドボックス環境で、データストアやサービスエンドポイントなどの異なる外部依存関係を使用する場合は、ダウンロードしたアーカイブを抽出し、environment.json ファイルを更新して、ディレクトリを zip アーカイブに圧縮します。詳細については、環境ファイルをご覧ください。
サンドボックスプロジェクトまたはテストアプリケーションで、アプリケーションメニューを開き、[Import] を選択して、アーカイブをアップロードします。
省略可: ソースアプリケーションから評価テストケースをエクスポートし、サンドボックスアプリケーションにインポートして、回帰テストを実行できるようにします。

ステップ 2: モデル設定を更新する

サポートされているモデルのリストを確認して、エージェントのモダリティ（テキストまたは音声）に一致するターゲット Gemini モデルを選択します。モデル設定は、コンソール、エクスポートされた構成ファイル、または REST API を使用して更新できます。

コンソールを使用してモデルを更新する

コンソールでエージェントアプリケーションを移行する場合は、グローバルアプリケーションモデル、個々のエージェントのオーバーライド、データストアツールモデル、フォールバック設定を確認します。

グローバルモデルを変更する:
1. エージェントビルダーで [設定] を開き、エージェントアプリケーションの設定を表示します。
2. [基本] > [インタラクション] で、[グローバルモデル] フィールドでターゲットモデルを選択します。このモデルは、オーバーライドを指定していないアプリケーション内のすべてのエージェントのデフォルトとして機能します。
ルートモデルとサブエージェントモデルのオーバーライドを確認する:
1. エージェントビルダーで、ルートエージェントのタイトルバーにあるメニューを開き、[構成を編集] を選択してエージェント設定を表示します。
2. [モデル] フィールドを確認します。エージェントがグローバルモデルをオーバーライドする場合は、ターゲットモデルを選択するか、オーバーライドをクリアしてエージェントがグローバルモデルを継承するようにします。
3. エージェント階層内のすべてのサブエージェントに対して、このチェックを繰り返します。
データストアツールモデルを確認する:
1. アプリケーションでデータストアツールを使用している場合は、[ツール] パネルを開き、各データストアツールを選択します。
2. [詳細] > [モダリティ] を展開し、[テキスト] と [音声] の両方の構成で [リライターモデル] と [要約モデル] の選択を確認します。
再試行とフォールバックの設定を確認する:
1. エージェントアプリケーションの [設定] を開き、[基本] > [動作] > [フォールバック動作] に移動します。
2. モデル生成中のエラー処理に、[再試行]、[エージェントのレスポンス]、[フォールバック] が適切に構成されていることを確認します。

エクスポートされた構成ファイルを使用してモデルを更新する

バージョン管理または CI / CD パイプラインでエージェントアプリケーションを管理している場合は、エクスポートされたアーカイブでモデル設定を更新し、パッケージを再インポートできます。

エクスポートしたエージェントアプリケーションの ZIP アーカイブを解凍します。
agents/<var>AGENT_NAME</var>/ の各エージェントディレクトリで、agents/<var>AGENT_NAME</var>/<var>AGENT_NAME</var>.yaml ファイルを開き、modelSettings.model フィールドをターゲットモデル ID に更新します。
```
displayName: "AGENT_NAME"
modelSettings:
  model: "MODEL_ID"
instruction: "agents/AGENT_NAME/instruction.txt"
```
次のように置き換えます。
- <var>AGENT_NAME</var>: エージェントの表示名。
- <var>MODEL_ID</var>: ターゲットモデルの識別子（gemini-3.5-flash や gemini-composite-v2 など）。
ルートディレクトリを ZIP アーカイブに圧縮し、更新されたアーカイブを CX Agent Studio にインポートします。

REST API を使用してモデルを更新する

CX Agent Studio REST API を使用して、エージェントアプリケーションと個々のエージェントの ModelSettings をプログラムで更新できます。

API を呼び出す前に、次の値を収集します。

<var>PROJECT_ID</var>: 実際の Google Cloud プロジェクト ID。
<var>LOCATION_ID</var>: エージェントアプリケーションのリージョン（us、eu など）。
<var>APP_ID</var>: エージェントアプリケーションのリソース ID。
<var>AGENT_ID</var>: 特定のルートエージェントまたはサブエージェントのリソース ID。
<var>MODEL_ID</var>: ターゲットモデル ID（gemini-3.5-flash など）。

エージェントアプリケーションのデフォルトのグローバルモデルを更新するには、updateMask=modelSettings を指定して projects.locations.apps.patch メソッドに PATCH リクエストを送信します。

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"
    }
  }'

個々のルートエージェントまたはサブエージェントのモデルオーバーライドを更新するには、updateMask=modelSettings を指定して projects.locations.apps.agents.patch メソッドに PATCH リクエストを送信します。

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"
    }
  }'

ステップ 3: エージェントのパフォーマンスを評価して改善する

基盤モデルは、推論スタイル、指示の遵守、詳細度、ツール呼び出しの動作が異なる場合があります。モデルを切り替えたら、エージェントをテストし、指示を調整してから、更新された構成にライブカスタマートラフィックをルーティングします。

シミュレータでインタラクティブにテストする

プレビューエージェントシミュレータで初期の健全性チェックを実行します。

エージェントビルダーでシミュレータを開き、[新しい会話を開始] をクリックします。
代表的なテキストまたは音声のインタラクションをテストし、エージェントが指示に従い、有効な引数でツールを呼び出し、想定どおりにサブエージェント間で移行することを確認します。
各ターンのトレースの詳細を開いて、ステップのレイテンシ、ツールの入力と出力、未加工の JSON レスポンスを検査します。
省略可: 会話を回帰スイートに追加するには、シミュレータメニューを開き、[Save as golden] を選択します。

AI を使用して評価を実行し、問題を診断する

評価を使用して、ゴールデン、シナリオ、シミュレーションのテストケース全体でパフォーマンスを測定し、結果をベースラインバージョンと比較します。

エージェントビルダーの上部にある [評価] をクリックします。
クリティカルユーザージャーニーとエージェントバリアントをカバーするテストケースを選択し、[選択したテストを実行] をクリックします。
実行ダイアログで [Find issues with AI] を選択し、最適な AI 分析のために実行回数を 3 回以上に設定して、実行を開始します。詳細については、AI を使用してテストケースを改善するをご覧ください。
実行が完了したら、ツールの正確性、セマンティックの一致、ユーザーの目標達成度、達成した目標、ハルシネーション、タスクの完了などの評価指標を確認し、失敗したターンや未完了の目標を調べます。
結果ページで [Gemini に相談] をクリックして、生成された loss_report を確認し、失敗した実行の根本原因を要約して、推奨される手順または構成の修正を確認します。

AI Co-Builder を使用したヒルクライムの手順: Arc

評価結果で、ターゲットモデルで回帰または動作の変化が示されている場合は、AI Co-Builder: Arc と評価ヘルパーを使用して、プロンプトを繰り返し改良します。

エージェントビルダーの上部にある [Arc] をクリックして、AI Co-Builder を開きます。
[コンテキストを選択] をクリックして、調整が必要な特定のエージェントまたは指示を選択するか、失敗した文字起こしと損失レポートを添付します。
他のテストケースでの動作を維持しながら、観察された失敗に対処するように指示またはツール記述を更新するよう Arc に指示します。指示の再構成機能を使用して、指示を構造化された形式に整理することもできます。
修正を適用した後に評価スイートを再実行し、すべてのテストケースが合格基準を満たすまで繰り返します。その他のガイダンスについては、評価とヒルクライムのベストプラクティスをご覧ください。

ステップ 4: トラフィック分割を使用して段階的にデプロイする

更新されたエージェントが評価に合格したら、バージョンとデプロイトラフィック分割を使用して段階的にロールアウトします。

移行したエージェントのバージョンを作成する

検証済みの構成の不変のスナップショットを保存します。

別のサンドボックスアプリケーションで変更をテストした場合は、検証済みのアプリケーションパッケージをエクスポートして、本番環境アプリケーションにインポートします。
本番環境アプリケーションで、[バージョン] ペインを開き、[+ バージョンを作成] をクリックします。
ターゲットモデルを識別する名前と説明（v2-gemini-3-5-flash など）を入力し、[作成] をクリックします。

ライブトラフィックを徐々に移行する

トラフィック分割を使用して、移行されたバージョンにトラフィックの 100% を昇格させる前に、ライブ会話のごく一部を移行されたバージョンにルーティングします。

エージェントビルダーの上部にある [デプロイ] タブをクリックし、デプロイチャネルを選択します。
[エージェントのバージョン] で [バージョンを追加] をクリックし、ベースラインの製品版と移行された候補バージョンの両方を追加します。
候補バージョンに小さな初期トラフィックの割合を割り当て（たとえば、ベースラインバージョンに 90%、候補バージョンに 10%、合計 100%）、チャネル構成を保存します。REST API を使用して、experimentConfig.versionRelease.trafficAllocations をプログラムで構成することもできます。
バージョン間でライブパフォーマンスをモニタリングする:
- モニタリングダッシュボードで、セッション数、レイテンシ、エスカレーション率を確認します。
- 会話履歴で音声文字変換を検査する。
- BigQuery で app_version_id を使用して、エクスポートされたインタラクションログをクエリし、バージョン間でツールの実行率と結果率を比較します。SQL クエリの例については、BigQuery でバージョンのパフォーマンスを分析するをご覧ください。
安定性と品質を確認しながら、移行したバージョンのトラフィックの割合を段階的に増やし、最終的にライブトラフィックの 100% を処理するようにします。ロールアウト中に予期しない問題が検出された場合は、トラフィックの 100% をベースラインバージョンにルーティングするか、[バージョン] ペインで以前のバージョンを復元します。