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 系统，代表客户的 Agent 配置。

• 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

Agent 的命名配置变体，用于 A/B 测试。运行时，配置覆盖项会与基础 Agent 的元数据进行深度合并。

• ID 格式：26 个字符的字符串
• 关键字段：display_name、description、config_overrides（深度合并的 JSON）、parameter_values（扁平化后用于显示）、status（ACTIVE/DELETED）
• 关系：通过 agent_id 隶属于某个 Agent
• 唯一约束：每个 (agent_id, display_name) 只能有一个有效的 mutation
• 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
• Persona 控制项：语音选择、背景噪声、打断频率（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（全局唯一的 slug）、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

运行

顶层执行实体。启动针对 Agent 的测试用例模拟。

• 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
• 运行类型：模拟运行（is_monitoring=false）与监控／对话运行（is_monitoring=true）
• 配置选项：iteration_count（1-50）、concurrency（1-100）、sub_sample_size、mutation_ids
• 模拟总数 = 测试用例数 x 迭代次数 x (1 + 变异数)
• API：GET/POST /v1/runs、GET/DELETE /v1/runs/{run_id}
• CLI：coval runs list|get|launch|watch|delete

模拟

针对 Agent 运行单个测试用例的结果（每个 test_case x iteration x variant 对应一条）。

• ID 格式：22 个字符的字符串
• 关键字段：run_id、test_case_id、iteration、mutation_id、mutation_name、transcript、status、audio_length_seconds、external_conversation_id、tool_calls
• 变异跟踪：mutation_id 和 mutation_name 用于标识所使用的变异版本。对于基础 Agent 模拟（无变异），两者均为 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

指标输出

使用特定指标评估单个模拟的结果。

• 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}

运行模板

可复用的已保存运行配置，用于安排计划。

• ID 格式：22 个字符的字符串
• 关键字段：display_name、agent_id、persona_id、test_set_id、metric_ids、mutation_ids、run_config（JSON 单一可信来源）
• 软删除：状态为 ACTIVE 或 DELETED
• API：GET/POST /v1/run_templates、GET/PATCH/DELETE /v1/run_templates/{id}

计划运行

基于 Cron／频率的计划任务，可从模板触发运行。

• ID 格式：22 个字符的字符串
• 关键字段：template_id、schedule_expression（cron 或 rate）、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. 创建变体：使用 config_overrides 调用 POST /v1/agents/{agent_id}/mutations
2. 使用 mutation_ids 数组启动运行
3. 列出模拟：调用 GET /v1/simulations?filter=run_id="{run_id}"
4. 按 mutation_id 分组（null = 基础 Agent）
5. 查询变体名称：调用 GET /v1/agents/{agent_id}/mutations
6. 比较各组的指标

安排定期评估

1. 创建运行模板，并设置 Agent、角色、测试集、指标和变体
2. 创建引用该模板的定时运行，并设置 cron/频率表达式
3. 运行会自动启动，并通过 scheduled_run_id 关联回模板

提交实时对话（监控）

1. 使用对话数据调用 POST /v1/conversations:submit
2. 创建一个 is_monitoring=true 的运行，其中包含单个模拟
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