coval-resources

Coval プラットフォームのリソース概要

$ARGUMENTS のリファレンスです。API 呼び出しやデータの調査を行う前に、Coval のリソースモデルを理解するために使用してください。

リソース階層

すべてのリソースは組織のスコープ内にあります（API キーによって決まります）。

Agent (22-char ID)
└── Mutation (26-char ID)
Test Set (8-char ID)
└── Test Case (22-char ID)
Persona (22-char ID)
Metric (22-char ID)
Run (22-char ID)
└── Simulation (22-char ID)
    └── Metric Output (26-char ID)
Run Template (22-char ID)
└── Scheduled Run (22-char ID)

リソース

Agent

評価対象となる AI システムです。顧客のエージェント設定を表します。

• ID 形式: 22 文字の文字列
• 主なフィールド: customer_agent_id（組織ごとに一意）、display_name、model_type、phone_number、endpoint、metadata、prompt、language、test_set_ids、metric_ids、attributes
• モデルタイプ: MODEL_TYPE_VOICE、MODEL_TYPE_OUTBOUND_VOICE、MODEL_TYPE_CHAT、MODEL_TYPE_WEBSOCKET、MODEL_TYPE_API、MODEL_TYPE_ENDPOINT
• 接続タイプ: インバウンド音声、アウトバウンド音声、OpenAI エンドポイント、Pipecat、LiveKit、WebSocket
• API: GET/POST /v1/agents、GET/PATCH/DELETE /v1/agents/{agent_id}
• CLI: coval agents list|get|create|update

Mutation

A/B テストで使用する、名前付きのエージェント設定バリアントです。設定のオーバーライドは、実行時にベースエージェントのメタデータとディープマージされます。

• ID 形式: 26 文字の文字列
• 主なフィールド: display_name、description、config_overrides（ディープマージされる JSON）、parameter_values（表示用にフラット化）、status（ACTIVE/DELETED）
• 関連: agent_id を介して Agent に属します
• 一意制約: (agent_id, display_name) ごとに有効な mutation は 1 つです
• API: GET/POST /v1/agents/{agent_id}/mutations、GET/PATCH/DELETE /v1/agents/{agent_id}/mutations/{mutation_id}
• CLI: coval mutations list|get

Test Set

何をテストするか（シナリオ、期待される動作）を定義するテストケースの集合です。

• ID 形式: 8 文字の文字列
• 主なフィールド: display_name、slug、description、test_set_type、parameters（JSON テンプレート変数）
• テストセットのタイプ: DEFAULT、SCENARIO、TRANSCRIPT、AUDIO、IVR、SCRIPT
• API: GET/POST /v1/test-sets、GET/PATCH/DELETE /v1/test-sets/{test_set_id}
• CLI: coval test-sets list|get|create|update

Test Case

テストセット内の個別のテストシナリオです。

• ID 形式: 22 文字の文字列
• 主なフィールド: input_str（シナリオ／プロンプト）、input_type、expected_behaviors（文字列の配列）、expected_output_json、description、simulation_metadata_input
• 入力タイプ: SCENARIO（自然言語のタスク）、TRANSCRIPT（OpenAI 形式の会話）、AUDIO（事前録音ファイル）、SCRIPT（順序付けられた行）、IVR、MANUAL
• 関連: Test Set に属します
• API: GET/POST /v1/test-cases、GET/PATCH/DELETE /v1/test-cases/{test_case_id}
• CLI: coval test-cases list|get|create|update

Persona

テスト中にシミュレートされたユーザーがどのように振る舞うか（音声、性格、中断のスタイル）を定義します。

• ID 形式: 22 文字の文字列
• 主なフィールド: display_name、simulated_user_prompt、voice_name、language_code、avatar_url、metadata
• ペルソナの設定項目: 音声の選択、背景ノイズ、中断頻度（NONE/LOW/MEDIUM/HIGH）、サイレントモード、発信者の電話番号
• 関連: Runs と Run Templates から参照されます
• API: GET/POST /v1/personas、GET/PATCH/DELETE /v1/personas/{persona_id}
• CLI: coval personas list|get|create|update

Metric

評価基準と採点方法の定義です。

• ID 形式: 22 文字の文字列
• 主なフィールド: metric_name（グローバルで一意なスラッグ）、display_name、description、metric_metadata（JSON 設定）、output_type、category
• 出力タイプ: FLOAT、STRING、SET、BOOLEAN
• 機能: 組み込みメトリクス、カスタム LLM ベースのプロンプト、メトリクスの連鎖、人間によるレビューとの連携、期待される動作の評価
• API: GET/POST /v1/metrics、GET/PATCH/DELETE /v1/metrics/{metric_id}
• CLI: coval metrics list|get|create|update

Run

最上位の実行エンティティです。エージェントに対するテストケースのシミュレーションを開始します。

• ID 形式: 22 文字の文字列
• 主要フィールド: agent_id、persona_id、test_set_id、display_name、status、config（JSON）、is_monitoring、tags、customer_metadata、scheduled_run_id
• ステータス: PENDING、IN QUEUE、IN PROGRESS、COMPLETED、FAILED、CANCELLED、DELETED
• Run の種類: シミュレーション Run（is_monitoring=false）とモニタリング／会話 Run（is_monitoring=true）
• 設定オプション: iteration_count（1～50）、concurrency（1～100）、sub_sample_size、mutation_ids
• シミュレーション総数 = test_cases x iterations x (1 + mutation_count)
• API: GET/POST /v1/runs、GET/DELETE /v1/runs/{run_id}
• CLI: coval runs list|get|launch|watch|delete

Simulation

エージェントに対して単一のテストケースを実行した結果です（test_case x iteration x variant ごとに 1 件）。

• ID 形式: 22 文字の文字列
• 主要フィールド: run_id、test_case_id、iteration、mutation_id、mutation_name、transcript、status、audio_length_seconds、external_conversation_id、tool_calls
• Mutation の追跡: mutation_id と mutation_name は、使用された Mutation バリアントを識別します。ベースエージェントのシミュレーション（Mutation なし）では、どちらも null です。
• API: GET /v1/simulations、GET/DELETE /v1/simulations/{simulation_id}、GET /v1/simulations/{simulation_id}/audio
• CLI: coval simulations list|get|audio|delete
• フィルタリング: mutation_id、mutation_name、agent_id、run_id、status、test_case_id、external_conversation_id、create_time に対応しています

Metric Output

特定のメトリックを使用して単一のシミュレーションを評価した結果です。

• ID 形式: 26 文字の文字列
• 主要フィールド: metric_output_id、metric_id、value（浮動小数点数、文字列、または配列）、status
• 関係: Simulation の子要素であり、Metric を参照します
• API: GET /v1/simulations/{simulation_id}/metrics、GET /v1/simulations/{simulation_id}/metrics/{metric_output_id}

Run Template

スケジュール設定に使用する、再利用可能な保存済み Run 設定です。

• ID 形式: 22 文字の文字列
• 主要フィールド: display_name、agent_id、persona_id、test_set_id、metric_ids、mutation_ids、run_config（JSON の信頼できる唯一の情報源）
• 論理削除: status=ACTIVE または DELETED
• API: GET/POST /v1/run_templates、GET/PATCH/DELETE /v1/run_templates/{id}

Scheduled Run

テンプレートから Run を開始する、Cron／レートベースのスケジュールです。

• ID 形式: 22 文字の文字列
• 主要フィールド: template_id、schedule_expression（Cron またはレート）、timezone、enabled
• 例: rate(15 minutes)、cron(0 2 * * ? *)
• API: GET/POST /v1/scheduled_runs、GET/PATCH/DELETE /v1/scheduled_runs/{id}

ID 形式の早見表

リソース	長さ	例
Agent	22	camudk3VhC3kmuvutXKLvF
Mutation	26	01KJ6N707FD9YEPKBSGX1KCW5V
Test Set	8	a1275ab2
Test Case	22	ac67b2c8916f41b6974084
Persona	22	nKexF9ZUt19tLtb3ZQsqzG
Metric	22	hUWu3PxY6G7fTYbLzBAwZm
Run	22	KNNxeP6Vfxx83K4TncVPLH
Simulation	22	LKuChNCLArtF8MLhBix5xY
Metric Output	26	01JCQR8Z9PQSTNVWXY123456
Run Template	22	abc123xyz789def456ghi0
Scheduled Run	22	xyz789abc123def456ghi0

よく使うワークフロー

評価を開始する

1. Agent、Test Set、Persona を特定します（CLI または API で一覧表示）
2. agent_id、test_set_id、persona_id、必要に応じて mutation_ids を指定して POST /v1/runs を実行します
3. GET /v1/runs/{run_id} をポーリングするか、coval runs watch {run_id} を使用します
4. 結果: GET /v1/simulations?filter=run_id="{run_id}" を実行し、各シミュレーションのメトリックを取得します

ミューテーションを比較する（A/B テスト）

1. ミューテーションを作成します：POST /v1/agents/{agent_id}/mutations に config_overrides を指定します
2. mutation_ids 配列を指定して実行を開始します
3. シミュレーションを一覧表示します：GET /v1/simulations?filter=run_id="{run_id}"
4. mutation_id でグループ化します（null はベースエージェントを示します）
5. ミューテーション名を確認します：GET /v1/agents/{agent_id}/mutations
6. グループ間でメトリクスを比較します

定期評価をスケジュールする

1. エージェント、ペルソナ、テストセット、メトリクス、ミューテーションを指定して実行テンプレートを作成します
2. cron／レート式を指定して、テンプレートを参照するスケジュール実行を作成します
3. 実行が自動的に開始され、scheduled_run_id で参照されます

ライブ会話を送信する（モニタリング）

1. 会話データを指定して POST /v1/conversations:submit を実行します
2. is_monitoring=true が設定され、シミュレーションが 1 つ含まれる実行が作成されます
3. メトリクスがリアルタイムで評価されます

API の規約

• ベース URL：https://api.coval.dev/v1
• 認証：X-API-Key ヘッダー
• ページネーション：page_size（1～1000、デフォルトは 50）、page_token。レスポンスには next_page_token が含まれます
• フィルタリング：AIP-160 構文 — filter=status="COMPLETED" AND agent_id="abc123"
• 並べ替え：order_by=-create_time（降順にするには接頭辞 - を指定）

ツールとリファレンス

• OpenAPI 仕様：GET https://api.coval.dev/v1/openapi — インテグレーションを構築する前に、必ず最新の仕様を取得してください
• CLI：https://github.com/coval-ai/cli — brew install coval-ai/tap/coval でインストールします
• MCP サーバー：https://github.com/coval-ai/mcp-server — LLM のツールアクセスに対応する Model Context Protocol サーバー
• ドキュメント：https://docs.coval.dev