setup-agent

エージェントのセットアップ

ユーザーが coval CLI を使って、新しい Coval エージェントを評価用に接続・設定できるよう案内します。以下のフェーズを順番に進め、各ステップで質問してください。

$ARGUMENTS にエージェント名または URL が含まれている場合は、該当するフィールドに事前入力し、その項目についての質問を省略してください。

Phase 0: 事前確認

Step 1: 認証を確認する

coval whoami

認証されていない場合は、ユーザーに次のように案内してください。

coval login

ここで API キーの入力を求められます。API キーは https://app.coval.dev/settings （Organization > Manage > API Keys）で取得できます。

Coval アカウントを持っていない場合は、https://coval.dev から登録するよう案内してください。

Step 2: 既存のエージェントを確認する

coval agents list --format json

エージェントが存在する場合は、番号付きリストを提示します。

Existing agents:

  1. My Voice Bot (voice) — +12345678901
  2. Support Chat (chat) — https://api.example.com/chat

  N. Create a new agent

「既存のエージェントを設定しますか、それとも新しいエージェントを作成しますか？」と質問します。

ユーザーが既存のエージェントを選んだ場合は、Phase 3（システムプロンプト）に進んで更新するか、プロンプトがすでに設定されている場合は Phase 4（デフォルトリソース）に進んでください。

エージェントが存在しない場合は、Phase 1 に進んでください。

Phase 1: エージェントの種類を選択する

「どの種類の AI エージェントをお持ちですか？」と質問します。

選択肢を提示します。

• voice — 着信電話に応答します（エージェントが電話に出ます）
• outbound-voice — エージェントから発信します（エージェントが通話を開始します）
• chat — テキスト／API エンドポイント（OpenAI 互換形式）
• sms — SMS ベースのエージェント
• websocket — WebSocket 接続（ws:// または wss://）

種類ごとに必要なフィールド、検証、よくある問題について説明した references/connection-types.md を読み込みます。Phase 2 での質問にこの情報を活用してください。

Phase 2: 接続を設定する

選択した種類に応じて、必要な接続情報を収集します。

voice / sms エージェントの場合：

「エージェントの電話番号を教えてください。（E.164 形式、例：+12345678901）」と質問します。

入力を検証します。

• + で始まること
• + の後は数字のみであること
• 国番号を含めて合計 10～15 桁であること

chat / outbound-voice / websocket エージェントの場合：

「エージェントのエンドポイント URL を教えてください。」と質問します。

入力を検証します。

• chat / outbound-voice：有効な HTTP/HTTPS URL であること
• websocket：有効な WebSocket URL（ws:// または wss://）であること

エージェント名：

「このエージェントにどのような名前を付けますか？」と質問します。

$ARGUMENTS に名前が指定されている場合は、「このエージェントの名前を『』にします。よろしいですか？」と確認します。

Phase 3: システムプロンプト（任意）

「エージェントのシステムプロンプトはありますか？ 貼り付けると、後でより良いテストケースやメトリクスを作成できます。」と質問します。

• ユーザーがプロンプトを入力した場合は、prompt フィールドに保存します。
• ユーザーが省略した場合は先に進みます。後から追加できます。

Phase 4: デフォルトリソース（任意）

既存のリソースを確認します。

coval test-sets list --format json
coval metrics list --format json

テストセットまたはメトリクスが存在する場合は、提示します。

Available test sets:
  1. Customer Support Evaluation (3 cases)
  2. Edge Case Suite (5 cases)

Available metrics:
  1. Composite Evaluation
  2. Call Resolution
  3. Custom: Identity Verification

「このエージェントにデフォルトのテストセットまたはメトリクスを関連付けますか？ これらは今後の実行でエージェントのデフォルト設定になります。」と質問します。

「はい」の場合は、選択した ID を収集してエージェントを更新します。

coval agents update <agent_id> --test-set-ids <id1>,<id2> --metric-ids <id1>,<id2>

リソースが存在しない場合は、セットアップ後に作成するよう提案します。

• 「セットアップ後に /build-test-suite でテストセットを、/configure-metrics でメトリクスを作成できます。」

Phase 5: 検証

エンドポイントベースのエージェント（chat、outbound-voice、websocket）の場合：

接続をテストするよう提案します。「エンドポイントに到達できるか確認しますか？」

「はい」の場合は、基本的な接続確認を試み、結果を報告します。

電話番号ベースのエージェント（voice、sms）の場合：

E.164 形式が正しく、番号が有効に見えることを確認します。

作成前にエージェントの概要を表示する：

Agent Summary:
  Name:     <name>
  Type:     <type>
  <Phone/Endpoint>: <value>
  Prompt:   <first 80 chars or "Not set">
  Defaults: <test sets and metrics or "None">

「このエージェントを作成しますか？（はい／編集）」と質問します。

エージェントを作成します。

# For voice/sms:
coval agents create --name "<name>" --type <type> --phone-number "<number>" --format json

# For chat/outbound-voice/websocket:
coval agents create --name "<name>" --type <type> --endpoint "<url>" --format json

JSON レスポンスから agent_id を取得します。

ユーザーがシステムプロンプトを入力している場合は、エージェントを更新します。

coval agents update <agent_id> --prompt "<prompt>"

デフォルトリソースが選択されている場合は、それらを関連付けます。

coval agents update <agent_id> --test-set-ids <ids> --metric-ids <ids>

作成したエージェントを確認します。

coval agents get <agent_id> --format json

フェーズ 6：概要と次のステップ

作成したエージェントを提示します：

Agent created successfully!

  ID:       <agent_id>
  Name:     <name>
  Type:     <type>
  <Phone/Endpoint>: <value>

  View in dashboard: https://app.coval.dev/agents/<agent_id>

ユーザーが設定した内容に基づいて、次のステップを提案します：

• テスト用のペルソナを設計する：/design-persona
• このエージェントのテストケースを作成する：/build-test-suite
• 評価するメトリクスを設定する：/configure-metrics
• オンボーディングの全フローを実行する：/onboard