cekura-flag-call-log-failures

flag-call-log-failures

检查某个 Agent 最近的生产环境通话日志，并产出以下三项：

1. 标记的通话——触发各项指定 KPI／问题／目标失败的通话 ID，以及逐字证据。
2. 失败率——每项失败占所有已审查通话日志的百分比。
3. 结果分布——将其余每通电话归入互斥的结果分类（例如：未接听／已完成筛选／未完成筛选——来电方原因／未完成筛选——Agent 问题），并给出各分类所占百分比，从而将标记出的失败情况置于整体样本中呈现。

这是前端分诊步骤：将标记出的通话集交给 cekura-generate-scenarios 来构建评估器，或者向用户提供分布数据，用于面向客户的质量报告。

此技能严格只读——绝不会创建、更新或删除任何内容。

最重要的任务是归因：只有在被测 Agent 导致问题时，通话才算作 Agent 失败。来电方导致的结束、模拟来电方断开连接，以及已恢复的通话，绝不能算作 Agent 失败——它们应归入各自的分类。

---

步骤 0 — 前提条件

通过 Cekura MCP 读取数据。确认以下工具均已连接：

• mcp__cekura__aiagents_retrieve — Agent 描述和预期行为（判定“失败”的标准）
• mcp__cekura__call_logs_list — 分页获取生产环境通话列表（轻量级：通常包含 id、duration、call_ended_reason、success 和汇总后的指标分数，但通常不含转录文本）
• mcp__cekura__call_logs_retrieve — 获取单通电话的完整转录文本和指标评估
• mcp__cekura__metrics_list — 查找已有的 KPI／问题评分指标（如果存在，应复用这些指标作为分类依据）

如果未连接 mcp__cekura__* 工具，请停止并告知用户连接 Cekura MCP（参见 /setup-mcp 或 https://docs.cekura.ai/mcp/overview）。

---

步骤 1 — 输入

对于未提供的信息，使用 AskUserQuestion 询问：

1. Agent ID（数字）。如果不知道，可使用 mcp__cekura__aiagents_list 查找。

2. （可选）Project ID。

3. 时间范围——最近多少通电话（默认 100），或指定日期范围。分批处理（见步骤 2）。

4. 要衡量的 KPI／问题／目标——这是请求的核心：

   • 明确的问题——例如：“在完成所有筛选问题前就结束的通话”、“Agent 对不明确的回答反复追问”、“背景噪声导致 Agent 停滞”。每项问题都将成为一个标记分类，并对应一个失败率。
   • KPI／目标——例如：“每通电话都应完整筛选候选人”、“已接听的通话中有多少比例可以改进”——将其反向转换为未达成目标的失败类型。
   • 没有具体要求 → “任何真实的 Agent 失败”，以 agent_description 为依据，并按照步骤 3 中的失败模式分类体系进行分类。

5. 结果分类体系——将所有通话分入其中的互斥分类。根据 Agent 的工作内容确定分类。候选人筛选 Agent 的自然分类为：

   • 未接听 · 已完成筛选 · 未完成筛选——来电方原因 · 未完成筛选——Agent／系统问题

   对于其他 Agent，请相应调整（例如：已解决／已升级处理／已放弃／Agent 错误）。汇报前先向用户确认分类集合。

在开始处理时间范围内的通话前，将问题清单和分类集合复述给用户确认。

---

步骤 2 — 分批获取，按成本从低到高分类

Agent 上下文 — mcp__cekura__aiagents_retrieve(id=...)：记录 agent_description、agent_name、project_id，以及用于定义 KPI 的所有 {{dynamic_variable}} 名称（例如 requiredScreeningQuestions）。

⚠️ 如果 agent_description 为空或只是占位内容，且没有提供明确的问题清单，请停止——此时判定为“失败”没有依据。请用户列出问题或补充完善描述。

通话日志 — 分批循环获取。 使用 mcp__cekura__call_logs_list，设置 page_size=20，遍历 page=1..K，直到覆盖整个时间范围。列表视图开销很小，因此先收集每通电话的低成本信号：

字段	用途
id、duration	标识、基于时长的启发式判断
call_ended_reason	谁或什么结束了通话（最重要的初筛信号）
success / status	汇总后的通过／失败状态
metrics[] 分数	如果 KPI 指标已运行（见下文），直接读取分数

先进行低成本初筛（启发式）→ 再核实候选项。 获取每份转录都很浪费，还可能超出 token 预算。应改为：

1. 先按 call_ended_reason + duration 分组。 有力的判断依据：
   • 时长很短（例如 < 25s）→ 无人接听／未参与
   • Agent 结束（Main agent-ended-call），且时长正常 → Agent 已完成其流程（暂定为通过审核）
   • 呼叫方／测试 Agent 结束（testing-agent-ended-call、customer-ended-call、Client disconnected）→ 呼叫方一侧（暂定）
   • 静默／超时（Ending conversation after N seconds of silence）→ 可能是 Agent／系统问题（需核实）
2. 仅对疑似 Agent 问题的候选项核对转录——静默超时、异常长的通话，以及启发式规则无法归类的通话。使用 call_logs_retrieve 获取这些转录（内容较大时会溢出到文件；请用脚本检测循环／重复，而不要直接在行内阅读）。
3. 通话时间长 ≠ 循环。 通话时间长并不自动意味着 Agent 失败——计入之前必须先核实。检查是否确实重复提问（同一条标准化后的 Agent 发言出现 ≥4 次），或是否不断编造问题。许多长通话只是审核得很全面（Agent／候选人的对话轮次约为 1:1，没有重复）。

分类时优先使用我们已配置的指标，前提是这些指标已关联到 Agent／项目——它们编码了精确的归因规则：

• Call not answered (no pickup / voicemail) → 定义无人接听类别（TRUE = 无人接听）。
• All vetting questions asked (perf) → 符合条件的通话中完成审核的判断依据（PASS = 已完成审核）。
• Testing agent ended call before hard vetting started → 呼叫方一侧的提前挂断（TRUE）。
• All vetting questions asked（失败标记）→ Agent 跳过了问题。

如果尚未针对该时间范围评估这些指标，可以触发评估（call_logs_evaluate_metrics_create——需要消耗评估额度，且为异步），以获取经过审核的数量；也可以根据转录／启发式规则进行分类，并将结果报告为估算值（注明所用方法）。

如果 call_logs_list 返回 0 条结果，请停止——这是一个尚未投入生产的 Agent，无需分诊。

---

第 3 步 — 对每次通话进行分类

对于每次通话，判断其结果类别（互斥），如果属于 Agent 失败，则判断问题／模式。标记为失败时，记录：

{ call_log_id, issue/mode, severity, evidence_quote, ended_reason, expected_behavior }

• evidence_quote — 逐字引用转录片段（或说明失败指标的依据）。不得改述；无法引用就不能标记。
• expected_behavior — 用一句话说明 Agent 本应采取的行为（此内容会传入场景的 expected_outcome_prompt）。

“任何真实失败”分类（没有明确问题列表时）：

Code	Mode	Detection signals
🛑 drop	由 Agent 提前结束	Agent 在工作流进行中结束通话／转接；Agent 端断开连接
🌀 drift	偏离任务／角色	内容与 agent_description 无关
👻 hallucination	编造知识库／描述中没有的事实	描述／知识库中不存在的数字／政策／产品
🔧 tool_error	工具选择／参数／工具调用后处理出错	工具报错；重复询问工具已回答的问题；使用了错误的工具
🎯 workflow_miss	漏掉／做错必需步骤	尚未询问所有必需问题就结束；跳过征求同意
🤔 comprehension	误解来电者	对同一个澄清问题重复询问 3 次以上；陷入循环且无法恢复
🔁 loop	陷入重复，始终无法推进	多次重复同一个问题／确认事项；不断编造问题
🚪 refusal	拒绝了合理且符合范围的请求	在其描述范围内回答“我无法帮助处理此事”
⚡ latency	长时间停顿／响应缓慢／无响应	回合间隔过长；来电者说完后没有回应
🧨 safety	泄露 PII／不安全内容	未经提示便复述 SSN／卡号；包含不允许的内容
📻 asr_capture	候选人发言但未被捕获	候选人发言回合显示为“…”；Agent 再次提示“你还在吗？”→静默超时（属于系统／ASR 类问题，可改进但不是提示词问题——需单独指出）

一次通话可能出现多个问题，但其结果只能归入一个类别。

---

第 3.5 步 — 归因与恢复规则（避免误报失败）

**只有当受测 Agent 导致问题时，才将通话计为 Agent 失败。**否则应归入非 Agent 类别。

1. 来电者侧／模拟来电者结束通话不算 Agent 失败。在 Agent 能完成通话之前，若 call_ended_reason ∈ {testing-agent-ended-call, customer-ended-call, Client disconnected: 1005/1012} → 归为未经审核的来电者侧结束，而非 Agent 失败。
2. 已恢复 = 不算失败。如果 Agent 遇到问题，但获得所需信息并继续推进，则不要标记。只有当 Agent 持续陷入困境／无法恢复／通话偏离正轨时才标记。
3. **合理的提前结束不算失败。**候选人拒绝、未满足硬性要求或要求回拨时，正确结束通话属于正确行为 → 计为干净／合理的结果，而非 Agent 失败。
4. 默认不标记 Agent 打断／截断用户——只有用户明确列出此项时才标记。

如果用户明确列出的问题与默认规则冲突（例如用户确实希望将来电者挂断计为问题），则遵循用户要求。

---

步骤 4 — 量化并分发

对完整审核集进行两项计算（令 N = 审核总数）：

A. 失败率。 对每个标记的问题：count / N = 存在该问题的通话日志占比。如果用户表述的是“已接通通话中的占比”，则改用已接通通话数作为分母（已接通 = N − 未接通，其中未接通对应 Call not answered 类别）。明确说明分母。

B. 结果分布。 将每通电话恰好归入一个类别，并报告数量和占比：

not answered            : a/N
vetted                  : b/N   (= b/answered)
non-vetted caller-side  : c/N   (= c/answered)
non-vetted agent/system : d/N   (= d/answered)   ← the improvable slice

必要时对类别进一步细分（Agent／系统类别通常可细分为 ASR-capture 和 true agent loop；来电方类别可细分为“审查开始前挂断”和“审查过程中挂断”——后者对应 Testing agent ended before hard vetting started 指标）。

突出可改进的数字： “已接通通话中有 X% 可以通过我们这边改进”（即 Agent／系统类别），并说明未审查通话总数中有多少属于来电方问题（而非 Agent 缺陷）。

---

步骤 5 — 报告

# Call-log failure analysis — <agent_name> (`<agent_id>`)

**Window:** last <N> calls (<start> → <end>) · **Answered:** <A>
**Criteria:** <the confirmed KPI/issue list>

## Outcome distribution
| Bucket | Count | % of all | % of answered |
|---|---|---|---|
| Not answered | a | a/N | — |
| Vetted | b | b/N | b/A |
| Non-vetted — caller-side | c | c/N | c/A |
| Non-vetted — agent/system (improvable) | d | d/N | d/A |

→ **~d/A% of answered calls are improvable on our side.** (Caller-side = c/A%, not an agent defect.)

## Flagged failures (agent/system) — call IDs + rate
| Issue | Rate (of all) | Calls (evidence) |
|---|---|---|
| ASR capture → silence drop | 6/N | [<id>](…) "are you still there?" ×N → timeout; … |
| Loop | 1/N | [<id>](…) re-asked "which shift?" ×6 |

## Methodology & confidence
- Which calls were transcript-verified vs. heuristic-bucketed (ended_reason + duration).
- If the agent/system count is a lower bound (issues hidden inside agent-ended/caller-ended calls weren't all read), say so.
- Whether numbers are audited (metrics evaluated) or estimated (heuristic).

规则：

• 每条通话引用都必须是指向 https://dashboard.cekura.ai/<project>/observe/<id> 的 Markdown 链接。
• 证据必须是逐字引用（可以附上“询问了 11 项中的 7 项”之类的简短注释）。
• 明确列出所有标记的 Agent／系统通话；对于数量较多的正常类别，只报告数量，绝不逐一列出正常通话 ID。
• 语气直接，以证据为依据。注明每个百分比的分母。

---

步骤 6 — 交接

标记了 通 Agent／系统通话（已接通通话的 <d/A>%）。需要我把这些转成回归场景吗？我可以将标记集交给 cekura-generate-scenarios，由它们聚类并为每种失败模式构建一个评估器。

如果用户同意，调用 cekura-generate-scenarios 并传入标记集——每个条目都已包含 {call_log_id, issue/mode, severity, evidence_quote, expected_behavior}，这正是它所需的逐通话记录（它会跳过自身的挖掘步骤，直接进行聚类）。不要在那里重新分诊。

---

何时停止／转向

• 单个已知通话 → 场景： 跳过分诊，直接调用 cekura-generate-scenarios（单通话快速路径）。
• 为什么某次运行失败（电话服务、未接通、SIP、转录为空）→ 这是运行调试，而非通话日志分诊；请检查该次运行的电话服务／Agent 配置，或联系 Cekura 支持。
• 没有生产环境通话日志（预生产 Agent）→ 停止；没有可供分诊的内容。