onboard

首次 Coval 评估

从客户的 Agent 入手，获取一项可信的评估证据。 建立可用连接是第一个里程碑；可信的任务质量检查则是另一项工作。不要把设置过程变成问卷，也不要创建所有可能的资源。

1. 明确上下文和访问权限

沿用客户所述的用例、端点和要求。只询问缺失的信息：Agent 必须完成什么任务、需要发现的一项重要失败，以及要使用哪个组织／工作区／环境。如果已有已完成的录制，除非用户想要重新运行，否则优先使用 coval-discover-failures。

coval --version
coval --agent agent doctor
coval --agent agent manifest

如果缺少安装或身份验证，请使用最新的 CLI 安装指南。让用户通过登录或其机密环境输入凭据，而不是在聊天中提供。Doctor 能证明连通性，但不能证明租户身份。在写入之前，请检查预期的账号上下文和所选资源。使用现有工作区；如果 CLI 无法选择该工作区，请使用公共 API 文档中所述的工作区请求头。

在该范围内检查现有 Agent、角色、测试集和指标。检查 JSON 信封（ok、data）、失败信息和分页。复用匹配的资源；仅凭名称并不足以确保写入安全。

2. 连接一个 Agent

阅读 coval agents create --help 和 coval --agent agents context；对于 CLI 未提供的字段，请获取最新的 agents 规范：https://api.coval.dev/v1/openapi/agents。选择实际使用的传输方式：电话、托管式语音到语音、语音 WebSocket、LiveKit/Pipecat、聊天、聊天 WebSocket、A2A 或 SMS。不要推断所有 WebSocket 连接都只是文本连接。请使用 Coval 文档索引中对应的连接指南。

如适用，请复用已配置的 Agent。若要建立新连接，请在本地准备符合架构的请求正文，展示脱敏后的摘要，并且只在请求的范围内创建。不要将凭据复制到技能、报告或 Git 中。创建后重新读取 Agent，并验证其传输方式和端点，但不要打印机密信息。URL 可访问或 Agent 记录已保存，并不代表语音连接成功。

3. 设计最精简有效的测试

使用 build-test-suite，根据客户的工作流拟定少量测试用例。先用 一个简短用例、一个常规角色、一次迭代和并发数 1，启动实时连接检查。然后，在约定的预算内，添加一条常规成功路径和一个重要的边界／失败用例。这只是起点，并非通用的三类分类法。

角色描述来电者是谁以及他们的行为方式。测试用例描述他们想要完成什么。预期行为描述Agent 必须怎么做。不要让来电者直接说出预期答案。目标得到回应后就结束场景；避免开放式对话。

对于语音，从公开角色目录中选择当前兼容的语音／语言；不要从过时模板中硬编码某个提供商的语音名称。使用现有的合适角色，或在检查架构后准备 coval personas create --input-json @persona.json。只有在基本连接正常后，且噪声、口音或打断与待验证假设相关时，才添加这些因素。

4. 选择可观测的评估标准

使用 configure-metrics 设置一项针对具体任务的评估标准；如有用，还可设置少量运行指标。动态发现指标 ID。不要附加一整套情绪、语气和问题解决评分，也不要仅为了评估一次运行而更改 Agent 的默认设置。

转录文本可以证明说了什么，但无法证明预约、付款或转账确实发生。对于这类说法，请使用工具调用记录或外部证据。新的评判标准在经过人工标签验证之前，只能视为暂定标准。

5. 执行并检查

使用选定的案例 ID 和明确的会话预算运行 quick-eval。 执行前展示将要运行的内容；遵守客户现有的授权。 注明调用次数、指标评估次数、配置的单次调用时长限制，以及墙钟时间停止条件。除非已知当前费率，否则不要将数量换算为美元。重新运行也计入同一预算。

审核每次首次运行的转录记录、状态、指标和录制内容。调用方是否执行了预期场景？双方的内容是否都在？指标是否针对正确的说话方和评估标准打分？请核对解释是否有证据支持。运行完成或单个示例得分完美，并不代表具有统计置信度。

如果连接失败，先诊断该次调用，再扩大测试套件。如果输出不可用，请报告缺失的证据及其对结果的影响。不要悄悄改用聊天、切换环境或持续重试。

6. 留下可复用的起点

返回创建或复用的资源 ID、已根据组织/工作区验证的运行和结果链接、实际模拟和指标数量、观察到的结果及其局限。建议最有用的下一步：检查失败、扩大覆盖范围或收集人工标注。只有在用户提出要求，或现有已达成一致的重复工作流需要时，才保存模板；创建计划属于单独操作。

保留资源以供检查。不要将其删除、修改生产环境中的 Agent 默认设置、发送邀请，或把安排后续跟进作为顺手的清理操作。