migrate-bluejay

Bluejay → Coval の移行

$ARGUMENTS のすべての設定を Bluejay から Coval に移行します。

API リファレンス

• references/bluejay-api.md — Bluejay のエンドポイント、認証、ページネーション
• references/coval-api.md — Coval のエンドポイント、認証、リクエストスキーマ
• references/entity-mapping.md — フィールドごとのマッピング表
• references/metric-type-mapping.md — Bluejay の response_type → Coval の metric_type

Step 0: 事前確認

API キーの収集

$ARGUMENTS から、位置引数を 2 つ解析します：[bluejay-api-key] [coval-api-key]。

指定されていない場合は、それぞれのキーを個別にユーザーに尋ねます。

Bluejay キーの検証

curl -s -o /dev/null -w "%{http_code}" \
  -H "X-API-Key: <BLUEJAY_KEY>" \
  "https://api.getbluejay.ai/v1/all-agents"

200 が返ることを確認します。401／403 の場合は、キーが無効であることをユーザーに伝えます。

Coval キーの検証

curl -s -o /dev/null -w "%{http_code}" \
  -H "X-API-Key: <COVAL_KEY>" \
  "https://api.coval.dev/v1/agents?page_size=1"

200 が返ることを確認します。401 の場合は、キーが無効であることをユーザーに伝えます。

Coval の音声カタログを取得

curl -s -H "X-API-Key: <COVAL_KEY>" \
  "https://api.coval.dev/v1/personas/voices"

Step 4 でペルソナをマッピングするために、音声リストを保存します。レスポンスの形式：

{ "voices": [{ "voice_name": "aria", "supported_languages": ["en-US", ...] }] }

Step 1: 棚卸し

Bluejay のすべてのエンティティを取得します。references/bluejay-api.md のエンドポイントを使用します。

可能な場合は、以下を並行して取得します：

エンティティ	エンドポイント
エージェント	GET /v1/all-agents
シミュレーション	GET /v1/get-all-simulations
カスタムメトリクス	GET /v1/custom-metrics?page=1&page_size=100（ページネーション）
コミュニティ	GET /v1/communities
スケジュール	シミュレーションから導出します（全件取得エンドポイントがないため、各シミュレーションを確認します）
顧客ペルソナ	エージェントごとに取得：GET /v1/customer-personas-by-agent/{agent_id}
フォルダー	GET /v1/all-folders

各エージェントについて、以下も取得します：

• 最新のプロンプト：GET /v1/agents/{agent_id}/prompts/versions?page_size=1（最新バージョン）
• 最新のナレッジベース：GET /v1/agents/{agent_id}/knowledge-bases/versions?page_size=1
• デジタルヒューマン：シミュレーションごとに取得：GET /v1/digital-humans-by-simulation/{simulation_id}

概要をユーザーに提示します：

Found:
  - X agents
  - Y digital humans (across Z simulations)
  - N custom metrics
  - M communities
  - P customer personas
  - Q schedules
  - R folders

Proceed with migration?

続行する前に、ユーザーの確認を待ちます。

Step 2: 既存の Coval 状態を確認

冪等性を確保するため、既存の Coval エンティティを取得します：

# Agents
curl -s -H "X-API-Key: <COVAL_KEY>" "https://api.coval.dev/v1/agents?page_size=100"

# Personas
curl -s -H "X-API-Key: <COVAL_KEY>" "https://api.coval.dev/v1/personas?page_size=100"

# Test Sets
curl -s -H "X-API-Key: <COVAL_KEY>" "https://api.coval.dev/v1/test-sets?page_size=100"

# Metrics
curl -s -H "X-API-Key: <COVAL_KEY>" "https://api.coval.dev/v1/metrics?page_size=100"

# Run Templates
curl -s -H "X-API-Key: <COVAL_KEY>" "https://api.coval.dev/v1/run-templates?page_size=100"

# Scheduled Runs
curl -s -H "X-API-Key: <COVAL_KEY>" "https://api.coval.dev/v1/scheduled-runs?page_size=100"

next_page_token がある場合は、ページネーションします。

各エンティティタイプについて、display_name → ID の参照マップを作成します。重複を確認するときは：

• メタデータに bluejay_migration: true があるエンティティは、スキップします（すでに移行済み）
• 移行されていないエンティティと名前が衝突する場合は、スキップするか名前を変更するかをユーザーに尋ねます

Phase 1: 独立したエンティティ（Steps 3–5）

これらには相互参照がありません。順番に実行しますが、各ステップは独立しています。

Step 3: メトリクスを移行

Bluejay のカスタムメトリクスを Coval のメトリクスにマッピングします。

Bluejay の各メトリクスについて、references/metric-type-mapping.md のマッピングを使用します。

各メトリクスについて：

1. Bluejay の response_type から metric_type を決定します
2. Bluejay の scoring_guidance と description から prompt を作成します
3. qualitative の場合は、カテゴリのリストをユーザーに尋ねます
4. quantitative の場合は、Bluejay の min_value／max_value があればそれを使用し、なければユーザーに尋ねます
5. enum の場合は、enum_options を categories として使用します
6. eval_route == "AUDIO" の場合は、METRIC_AUDIO_LLM_* バリアントを使用します
7. json の場合は、METRIC_LLM_BINARY を使用し、近似であることをユーザーに警告します

curl -s -X POST "https://api.coval.dev/v1/metrics" \
  -H "X-API-Key: <COVAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "metric_name": "<bluejay_metric_name>",
    "description": "<bluejay_description>",
    "metric_type": "<mapped_type>",
    "prompt": "<from_scoring_guidance>",
    "metadata": {
      "bluejay_migration": true,
      "bluejay_original_id": "<bluejay_metric_id>"
    }
  }'

マッピング表に従って、タイプ固有のフィールド（categories、min_value、max_value）を追加します。

記録：bluejay_metric_id → coval_metric_id

Step 4: ペルソナを移行

Bluejay のデジタルヒューマン（音声／動作）と顧客ペルソナを、Coval のペルソナにマッピングします。

デジタルヒューマン → ペルソナ

一意のデジタルヒューマンごとに、次を行います。

1. 音声マッピング — Bluejay の音声設定をユーザーに提示します。

   Bluejay Digital Human: "<name>"
     Gender: <gender>
     Accent: <accent>
     Language: <language>
   
   Available Coval voices: aria, asteria, athena, luna, ...
   
   Which Coval voice should map to this configuration?
   

   音声マッピングをキャッシュします。同じ性別＋アクセント＋言語の組み合わせが再び現れた場合は、質問せずにマッピングを再利用します。

2. language を language_code にマッピングします（例：en → en-US、es → es-ES）。

3. background_noise を background_sound にマッピングします（エンティティマッピングのリファレンスを参照）。

4. role_description + traits + 行動に関するフィールドから persona_prompt を作成します。

curl -s -X POST "https://api.coval.dev/v1/personas" \
  -H "X-API-Key: <COVAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<digital_human_name>",
    "voice_name": "<mapped_coval_voice>",
    "language_code": "<mapped_language_code>",
    "persona_prompt": "<built_from_role_description_and_traits>",
    "background_sound": "<mapped_background_noise>",
    "conversation_initiation": "<from_speaks_first_config>",
    "metadata": {
      "bluejay_migration": true,
      "bluejay_original_id": "<digital_human_id>"
    }
  }'

記録：bluejay_digital_human_id → coval_persona_id

カスタマーペルソナ → ペルソナ

Bluejay のカスタマーペルソナごとに、次を行います。

curl -s -X POST "https://api.coval.dev/v1/personas" \
  -H "X-API-Key: <COVAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<customer_persona_name>",
    "voice_name": "aria",
    "language_code": "en-US",
    "persona_prompt": "Name: <name>\nDescription: <description>\nGoal: <goal>",
    "metadata": {
      "bluejay_migration": true,
      "bluejay_original_id": "<customer_persona_id>",
      "bluejay_entity_type": "customer_persona"
    }
  }'

カスタマーペルソナに使用する音声をユーザーに尋ねます（デフォルトは aria）。

ステップ 5：エージェントを移行する

Bluejay エージェントを Coval エージェントにマッピングします。

Bluejay エージェントごとに、次を行います。

1. model_type を決定します。Bluejay の mode=VOICE → MODEL_TYPE_VOICE、mode=TEXT → MODEL_TYPE_TEXT
2. 最新のプロンプトバージョンの prompt_text + エージェントの goals（番号付きリストとして追加）から prompt を作成します。
3. エージェントに system_prompt がある場合は、それをプロンプトの先頭に追加します。
4. knowledge_base の内容をエージェントのメタデータに保存します。
5. エージェントに folder がある場合は、フォルダー名を display_name の先頭に付けます："[FolderName] AgentName"

curl -s -X POST "https://api.coval.dev/v1/agents" \
  -H "X-API-Key: <COVAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "<folder_prefix><agent_name>",
    "model_type": "<MODEL_TYPE_VOICE|MODEL_TYPE_TEXT>",
    "prompt": "<system_prompt + latest_prompt + goals>",
    "metadata": {
      "bluejay_migration": true,
      "bluejay_original_id": "<bluejay_agent_id>",
      "knowledge_base": "<kb_text_content>",
      "bluejay_connection_type": "<connection_type>",
      "bluejay_phone_number": "<phone_number>"
    }
  }'

記録：bluejay_agent_id → coval_agent_id

フェーズ 2：フェーズ 1 に依存（ステップ 6～7）

ステップ 6：テストセットを移行する

Bluejay のシミュレーション + コミュニティを Coval のテストセットにマッピングします。

シミュレーション → テストセット

Bluejay のシミュレーションごとに、次を行います。

curl -s -X POST "https://api.coval.dev/v1/test-sets" \
  -H "X-API-Key: <COVAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "<simulation_name>",
    "description": "Migrated from Bluejay simulation <simulation_id>",
    "test_set_type": "SCENARIO",
    "test_set_metadata": {
      "bluejay_migration": true,
      "bluejay_original_id": "<simulation_id>",
      "bluejay_entity_type": "simulation"
    }
  }'

記録：bluejay_simulation_id → coval_test_set_id

コミュニティ → テストセット

Bluejay のコミュニティごとに、次を行います。

curl -s -X POST "https://api.coval.dev/v1/test-sets" \
  -H "X-API-Key: <COVAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "<community_title>",
    "description": "<community_description>",
    "test_set_type": "SCENARIO",
    "test_set_metadata": {
      "bluejay_migration": true,
      "bluejay_original_id": "<community_id>",
      "bluejay_entity_type": "community"
    }
  }'

記録：bluejay_community_id → coval_test_set_id

ステップ 7：テストケースを移行する

Bluejay のデジタルヒューマンのインテントを Coval のテストケースにマッピングします。

シミュレーションに関連付けられたデジタルヒューマンごとに、次を行います。

1. intent を input_str として使用します。
2. success_criteria を expected_behaviors として使用します（複数行の場合は配列に分割します）。
3. シミュレーションのマッピング（ステップ 6）から coval_test_set_id を参照します。
4. scripted_responses がある場合は、input_type: "SCRIPT" を設定し、simulation_metadata_input.script_turns を指定します。

curl -s -X POST "https://api.coval.dev/v1/test-cases" \
  -H "X-API-Key: <COVAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "test_set_id": "<coval_test_set_id>",
    "input_str": "<digital_human_intent>",
    "expected_behaviors": ["<success_criteria_line_1>", "<success_criteria_line_2>"],
    "description": "<digital_human_name>: <digital_human_tag>",
    "input_type": "SCENARIO",
    "metadata": {
      "bluejay_migration": true,
      "bluejay_original_id": "<digital_human_id>"
    }
  }'

スクリプト形式のテストケースの場合：

curl -s -X POST "https://api.coval.dev/v1/test-cases" \
  -H "X-API-Key: <COVAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "test_set_id": "<coval_test_set_id>",
    "input_str": "<digital_human_intent>",
    "expected_behaviors": ["<success_criteria>"],
    "input_type": "SCRIPT",
    "simulation_metadata_input": {
      "script_turns": ["<turn_1>", "<turn_2>", "..."]
    },
    "metadata": {
      "bluejay_migration": true,
      "bluejay_original_id": "<digital_human_id>"
    }
  }'

記録：bluejay_digital_human_id → coval_test_case_id

フェーズ 3：フェーズ 1 + 2 に依存（ステップ 8）

ステップ 8：実行テンプレートを移行する

Bluejay のシミュレーションを Coval の実行テンプレートにマッピングします。

Bluejay のシミュレーションごとに、移行したリソースを関連付ける実行テンプレートを作成します。

1. シミュレーションのエージェントに対応する bluejay_agent_id から coval_agent_id を参照します。
2. このシミュレーションのデジタルヒューマンからマッピングされた最初のペルソナを選ぶか、ユーザーに尋ねます。
3. シミュレーションのマッピングから coval_test_set_id を参照します。
4. エージェントに関連付けられたメトリクスから coval_metric_ids を収集します。

curl -s -X POST "https://api.coval.dev/v1/run-templates" \
  -H "X-API-Key: <COVAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "<simulation_name> Template",
    "description": "Migrated from Bluejay simulation <simulation_id>",
    "agent_id": "<coval_agent_id>",
    "persona_id": "<coval_persona_id>",
    "test_set_id": "<coval_test_set_id>",
    "metric_ids": ["<coval_metric_id_1>", "<coval_metric_id_2>"],
    "iteration_count": 1,
    "concurrency": 5,
    "metadata": {
      "bluejay_migration": true,
      "bluejay_original_id": "<simulation_id>"
    }
  }'

記録：bluejay_simulation_id → coval_run_template_id

フェーズ 4：フェーズ 3 に依存（ステップ 9）

ステップ 9：スケジュール実行を移行する

Bluejay のスケジュールを Coval のスケジュール実行にマッピングします。

安全のため、スケジュール実行はすべて無効の状態で作成されます。 顧客はレビュー後に手動で有効にする必要があります。

Bluejay のスケジュールごとに、次を行います。

1. シミュレーションのマッピングから coval_run_template_id を参照します。
2. スケジュール形式を変換します。
   • Bluejay の cron 式 → Coval の cron(...) 形式
   • Bluejay の every_n_minutes → rate(<n> minutes)
   • Bluejay の every_n_hours → rate(<n> hours)
   • HH:MM に実行する Bluejay の daily → cron(<MM> <HH> ? * * *)
   • Bluejay の weekly → cron(<MM> <HH> ? * <DAY> *)
   • Bluejay の monthly → cron(<MM> <HH> <DOM> * ? *)

curl -s -X POST "https://api.coval.dev/v1/scheduled-runs" \
  -H "X-API-Key: <COVAL_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "<simulation_name> Schedule",
    "run_template_id": "<coval_run_template_id>",
    "schedule_expression": "<converted_schedule>",
    "enabled": false,
    "metadata": {
      "bluejay_migration": true,
      "bluejay_original_id": "<schedule_id>"
    }
  }'

記録：bluejay_schedule_id → coval_scheduled_run_id

ステップ 10：移行レポート

最終的な概要を出力します。

## Migration Complete

### Created Entities

| Type | Count | Details |
|------|-------|---------|
| Metrics | N | bluejay_id → coval_id for each |
| Personas | N | ... |
| Agents | N | ... |
| Test Sets | N | ... |
| Test Cases | N | ... |
| Run Templates | N | ... |
| Scheduled Runs | N | (all disabled) |

### Skipped (Already Existed)
- List any entities skipped due to idempotency

### Warnings
- List any ambiguous mappings or approximations made
- Note any `json` metrics mapped to METRIC_LLM_BINARY
- Note any voice mappings that may need review

### Next Steps
1. Review migrated entities in the Coval dashboard: https://app.coval.dev
2. Enable scheduled runs after verifying configuration
3. Run a test evaluation from a migrated Run Template to verify
4. Review persona voice assignments and adjust if needed

エラー処理

• HTTP 429（レート制限）：5秒待ってから再試行します。リクエストごとの再試行は最大3回です。
• HTTP 400（不正なリクエスト）：エラーの詳細をユーザーに表示します。入力を修正して再試行するか、このエンティティをスキップするかを尋ねます。
• HTTP 401/403（認証エラー）：処理を停止し、API キーを確認するようユーザーに求めます。
• HTTP 500（サーバーエラー）：エラーを表示し、このエンティティをスキップして、ほかのエンティティの処理を続行します。
• ネットワークエラー：3秒後に1回再試行します。それでも失敗する場合は、処理を停止し、ここまでに作成されたものを報告します。

失敗が発生した後は、ユーザーが処理を再開できるよう、ここまでに正常に作成されたものを必ず表示します。

冪等性ルール

1. エンティティを作成する前に、ステップ2の名前検索を確認します
2. エンティティが存在し、メタデータに bluejay_migration: true が含まれている場合は、何も通知せずスキップします
3. 移行元ではないエンティティと名前が重複する場合は、ユーザーに「Coval の <entity_type>『』はすでに存在しますが、Bluejay から移行されたものではありません。スキップ、名前変更、上書きのどれにしますか？」と尋ねます
4. 作成するすべてのエンティティに、次のメタデータを付与します：{ "bluejay_migration": true, "bluejay_original_id": "<id>" }
5. 変更がない場合、移行を再実行しても新しいエンティティは作成されません