cxas-dfcx-migration

DFCX から CXAS への移行

4 つの小さなスクリプトと 1 つの永続的な IR バンドル：

スクリプト	処理内容	実行時間	出力
migrate.py	選択したすべてのプレイブック／フローを IR に 1 対 1 で変換し、基本リソースのみ（アプリ、変数、ツール）をデプロイします。大規模なソースが CXAS の 100 エージェント上限を超えないよう、エージェントのデプロイは stage_1.py まで延期されます。コンパイル済みエージェントは <target>_ir.json に保存され、プッシュされません。完全な 1 対 1 のエージェントセットをすぐにプッシュするには、--no-consolidate を渡します（エージェントが約 100 個未満の場合のみ安全です）。	約 40 フローで約 30 分	<target>_ir.json、<target>_migration_report.md、<target>_unit_tests.json
stage_1.py	IR バンドルを読み込み、CXASOptimizer.optimize_stage1（変数の重複排除）と Gemini による構造的な統合（N 個から M 個へのエージェントグループ化）を実行します。CXAS への最初のエージェントプッシュです。統合後の（N 個から M 個にまとめられた）エージェントのみがデプロイされ、元の 1 対 1 のエージェントは一切プッシュされません（consolidate() が元のエージェントを破棄します。また、統合前のスナップショットは整合性チェック時のみ一時的に使用され、永続化されません）。CXAS バージョン 0.0.2（重複排除）および 0.0.3（統合）。	約 15 分	更新された <target>_ir.json、<target>_grouping.json
stage_2.py	IR バンドルを読み込み、CXASOptimizer.optimize_stage2（指示のステートマシンとツールのモック）を実行します。更新パスのデプロイでプッシュします。CXAS バージョン 0.0.4。ユニットテストを再生成し、Lint を実行して、監査レポートを書き込みます。	約 10 分	更新された <target>_ir.json、<target>_optimization_report.md、再生成された <target>_unit_tests.json
stage_3.py	ステージ 1 の統合後にのみ実行してください。 Spoke-Hub アーキテクチャスタイルに従い、合成された PIF XML が参照していた内容に依存するのではなく、ソース DFCX の依存関係グラフを新しいグループにマッピングすることで、統合後のエージェントの親子トポロジーを組み直します。アプリの root_agent を is_root グループに設定します。冪等性があるため、安全に再実行できます。CXAS バージョン 0.0.5。	約 10 秒	<target>_ir.json のステージ履歴を更新。CXAS アプリの child_agents をグループごとに設定

状態は <target>_ir.json（MigrationConfig、ソースの DFCXAgentIR、ターゲットの MigrationIR、ステージ履歴、バージョンチェックポイントを含む Pydantic の IRBundle）を通じて引き継がれます。各ステージはファイルから読み込み、変更を加えて書き戻します。ステージ間で再取得や再コンパイルは行いません。

このスキルと CLI の直接利用を使い分けるには

このスキル（InquirerPy プロンプト + HTML による事前プレビュー + Gemini モデル選択）は、充実した事前情報を確認しながら移行を対話形式で実行したい場合に適しています。このスキルが呼び出す MigrationService.run_stage* メソッドは、スクリプトや CI からの利用向けに、標準 CLI からも実行できます。

# Same E2E plumbing, non-interactive (standard optimized profile by default):
cxas migrate dfcx --run --source-agent-id … --project-id … --target-name …

# Non-interactive Stage Checkpoint optimization runs:
cxas migrate dfcx --optimize --stage 1 --target-name my_app
cxas migrate dfcx --optimize --stage 2 --target-name my_app
cxas migrate dfcx --optimize --stage 3 --target-name my_app --architecture hub-and-spoke
cxas migrate dfcx --optimize --stage resume --target-name my_app  # interactive stage picker

このスキル、ダッシュボード、E2E／チェックポイントコマンドは、すべて同じ MigrationService.run_stage_1/run_stage_2/run_stage_3 メソッドを呼び出します。ワークフローに合ったエントリーポイントを選んでください。

前提条件

# Ensure cxas_scrapi is installed editable (so this skill picks up local changes)
pip install -e .

# Auth
gcloud auth application-default login
gcloud auth list   # confirm the account has read on source + admin on target

対話形式のプロンプトには InquirerPy が必要です（agent-foundry スキルと同じです）。

pip install InquirerPy

対話形式での移行フローの実行（Claude から）

Claude 経由で呼び出す場合は、ユーザーに一度に 1 つずつ質問してください。スクリプトは不足している入力を InquirerPy で尋ねますが、事前に次の項目を確認してください。

1. GCP プロジェクト ID（ターゲット — 新しい CXAS アプリが配置される場所）。
2. ロケーション — デフォルトは us です。global をデフォルトにしないでください。ほとんどのプロジェクトでは CXAS アプリで動作しません。
3. ソースエージェント — DFCX エージェント ID（完全なリソース名）またはローカルの .zip エクスポートへのパス。
4. ターゲット名 — 新しい CXAS アプリの表示名。

任意の追加項目：--env（PROD/AUTOPUSH）、--model（Gemini）、--migration-version（1.0/2.0）。

クイックリファレンス

# 1:1 migration (interactive — InquirerPy will prompt for project + location)
python .agents/skills/cxas-dfcx-migration/scripts/migrate.py

# Fully scripted
python .agents/skills/cxas-dfcx-migration/scripts/migrate.py \
  --source-agent-id "projects/<src_proj>/locations/us/agents/<uuid>" \
  --project-id <target_proj> --location us \
  --target-name my_cxas_app --yes

# Pre-flight HTML preview only (no migration)
python .agents/skills/cxas-dfcx-migration/scripts/migrate.py \
  --source-agent-id "<id>" --project-id <proj> --target-name preview_only \
  --preview-only --yes

# Stage 1 — variable dedup + Gemini consolidation
python .agents/skills/cxas-dfcx-migration/scripts/stage_1.py --target-name my_cxas_app

# Stage 1 — replay a saved grouping JSON
python .agents/skills/cxas-dfcx-migration/scripts/stage_1.py \
  --target-name my_cxas_app --grouping-json my_cxas_app_grouping.json --yes

# Stage 2 — instruction state machines + tool mocks + lint + report
python .agents/skills/cxas-dfcx-migration/scripts/stage_2.py --target-name my_cxas_app

# Stage 3 — rewire consolidated agent parent-child topology (idempotent)
python .agents/skills/cxas-dfcx-migration/scripts/stage_3.py --target-name my_cxas_app --architecture hub-and-spoke

スキルと cxas_scrapi に含まれるもの

スキルは薄いオーケストレーターです。すべての移行／最適化ステップは src/cxas_scrapi/migration/ にあり、MigrationService.run_stage_* メソッドから利用できます。そのため、同じロジックが次の 3 つのエントリーポイントすべてで使われます。このスキル、cxas migrate dfcx（対話型 TUI）、および非対話型コマンドモード（--run ／ --optimize）です。

操作	src/ エントリーポイント
ソースエージェントの取得／zip の解析	migration/dfcx_exporter.py:ConversationalAgentsAPI
1:1 の移行	migration/service.py:MigrationService.run_migration
ステージ 1 オーケストレーター（変数の重複排除＋統合＋整合性確認＋トポロジーリンク＋孤立要素のクリーンアップ＋バージョン＋バンドルの永続化）	migration/service.py:MigrationService.run_stage_1
ステージ 2 オーケストレーター（ステートマシン＋ツールのモック＋単体テストの再生成＋lint＋監査レポート＋バンドルの永続化）	migration/service.py:MigrationService.run_stage_2
ステージ 3 オーケストレーター（親子トポロジーの接続）	migration/service.py:MigrationService.run_stage_3
バンドル永続化の便利メソッド	migration/service.py:MigrationService.persist_bundle
変数重複排除のプリミティブ（ステージ 1）	migration/optimizer.py:CXASOptimizer.optimize_stage1
指示の再構成＋ツールのモックのプリミティブ（ステージ 2）	migration/optimizer.py:CXASOptimizer.optimize_stage2
Gemini による N→M グループ化＋グループごとの PIF XML 生成	migration/structural_consolidator.py:StructuralConsolidator
デプロイ前の整合性確認	migration/integrity_checks.py:check_consolidation_integrity
親子トポロジー＋孤立要素のクリーンアップ	migration/topology_wirer.py
更新パスでの再デプロイ	migration/service.py:MigrationService._deploy_base_resources(is_update_pass=True) + _deploy_pending_agents(is_update_pass=True)
トポロジーリンク	migration/cxas_topology_linker.py
バージョンのチェックポイント	core/versions.py:Versions.create_version
トポロジー SVG	migration/graph_visualizer.py:HighLevelGraphVisualizer
リソースごとの Rich ツリー	migration/playbook_visualizer.py + migration/flow_visualizer.py
決定論的な単体テスト	migration/eval_generator.py:DeterministicEvalGenerator
移行レポート	migration/dfcx_migration_reporter.py
最適化監査レポート	migration/optimization_reporter.py:OptimizationReporter
グループ化レビュー TUI（承認／再提案／統合／分割／名前変更）	cli/grouping_review.py:interactive_review
HTML の事前確認プレビュー	migration/html_preview.py
デプロイ後のリンター	migration/post_deploy_lint.py
IR バンドルの永続化	migration/data_models.py:IRBundle

スキル内のヘルパー（UX の接着部分のみ — InquirerPy プロンプト＋MigrationCLI への薄い委譲）：

• _prompts.py — InquirerPy プロンプトライブラリ（agent-foundry と同じ構成です）。
• _shared.py — プロジェクト／ロケーションのプロンプト、ソースローダー、MigrationConfig の組み立てを行う InquirerPy バリアントです。また、check_auth、run_dependency_analysis、select_resources、show_visualizations を MigrationCLI に純粋に委譲します。

ステージスクリプトは、昇格されたモジュールを直接インポートするようになりました： from cxas_scrapi.migration.data_models import IRBundle （さらに migrate.py と phase_tracker では html_preview もインポートします）。呼び出し箇所では標準のモデル名（IRBundle、phase_tracker.PhaseTracker、 html_preview.generate_html_report）を使用するため、再エクスポートの中間層はありません。

スキルのステージスクリプト（migrate.py ／ stage_1.py ／ stage_2.py ／ stage_3.py）は、現在およそ 80～200 行のシェルになっています。引数を解析 → バンドルからサービスを復元 → 対応する MigrationService.run_stage_* を呼び出す → 概要を表示します。スキル内にオーケストレーションロジックは残っていません。InquirerPy プロンプトと、スキルの事前確認 UX に特化した HTML プレビューのみです。スキルの事前確認 UX に特化した HTML プレビューのみです。

IR バンドル（<target>_ir.json）

3 つのスクリプト間で共有される状態の単位です。Pydantic の IRBundle モデル：

{
  "schema_version": "1",
  "created_at": "2026-05-14T15:30:00",
  "config": { /* MigrationConfig */ },
  "source_agent_data": { /* DFCXAgentIR — needed for tool-mock context */ },
  "ir": { /* MigrationIR — mutated by each stage */ },
  "stage_history": [
    {"phase": "migrate", "status": "ok", ...},
    {"phase": "stage1",  "status": "ok", ...}
  ],
  "app_url": "https://ces.cloud.google.com/...",
  "version_checkpoints": [["0.0.1", "Stage 1: ..."]],
  "grouping": { /* present if Stage 1 ran consolidation */ }
}

ステージスクリプトを実行中に停止しても、バンドルは変更されません（成功時にのみ永続化されます）。再実行すると、最後に成功したステージの続きから処理されます。

事前チェック用 HTML プレビュー

migrate.py は、ソースの読み込み後、約 5 秒で <target>_tree_preview.html を生成します。任意のブラウザーで開くと、次の内容を確認できます。

• ソースの概要（リソース数、推定移行時間）。
• トポロジーグラフ（dot が PATH 上にある場合は graphviz SVG、それ以外の場合は Mermaid による代替表示）。
• Playbook とフローごとの Rich ツリー。

migrate.py --preview-only を実行すると、移行を開始せずにプレビューの生成後に終了します。

トラブルシューティング

• create_app が 404 / 501 / MethodNotImplemented を返す — --location が間違っています。ほとんどのプロジェクトで CXAS アプリは global ではなく us にあります。--location us を指定してください。
• AlreadyExists: App with same display name — 別の --target-name を指定してください。部分的に失敗した場合でも、以前の実行でデプロイされたアプリが残ることがあります。
• ステージ 1／ステージ 2 が No IR bundle found で失敗する — 先に migrate.py を実行して <target>_ir.json を生成するか、--ir-bundle <path> を明示的に指定してください。
• 合成（ステージ 1 の統合）が Gemini で停止する — structural_consolidator.synthesize_instructions で、グループごとに asyncio.wait_for(timeout=600s) を使用するよう修正されています。SYNTHESIS_TIMEOUT_S 環境変数で上書きできます。停止したグループでは、連結した指示にフォールバックします。
• AI による補完中に gemini-2.5-flash-001 not found が発生する — Gemini の呼び出しではモデルに locations/global を使用しますが、そのエンドポイントがプロジェクトによって制限されている場合があります。移行は AI による説明が空のまま続行されます。説明が必要な場合は、別の --model を指定してください。

詳細リファレンス

パラメーターとフラグの詳細、および IR バンドルのスキーマについては、references/migration-options.md を参照してください。