MCP 工具调用都成功，用户为何仍完不成任务？用 Armature 把 Agent 会话变成可修复的产品信号
给 MCP 服务接上日志和指标之后，很多团队会误以为自己已经看清了产品质量：HTTP 状态正常、工具调用耗时可控、错误率很低。但这只能说明服务端大致没有崩溃，不能说明用户借助 Claude、ChatGPT 或编码 Agent 完成了目标。
一个很常见的反例是：Agent 为了“给客户创建订阅并开票”连续调用了查询、创建和发送工具；每次调用都返回 200，最后却因为缺少账单联系人而反复重试，或者选择了错误的对象。传统 API 日志能显示调用顺序，却很难回答三个产品问题：用户真正想完成什么？Agent 为什么绕路？这一类失败影响了多少会话？
Armature 是面向 MCP 与 CLI 接口的产品分析和评测平台。它的切入点不是替代 OpenTelemetry 一类服务可观测性，而是把 Agent 调用你的接口时形成的会话重建为产品信号：归纳使用场景，聚类问题，并把真实工作流变成后续可重复运行的评测。它适合已经向 Agent 暴露 MCP 或 CLI 的团队；如果你只需要服务端的延迟、异常和资源指标，现有可观测性工具仍然是更直接的选择。
把“调用成功”与“任务成功”分开看
MCP 的特殊之处在于，人类的目标、Agent 的推理和工具调用发生在不同边界：用户在 AI 客户端对话，MCP 服务只看到请求。于是一个接口即使从不报错，也可能因为命名难懂、分页行为不明显、权限错误提示不够可操作而让 Agent 失败。
Armature 的页面将这类问题拆成三个层次：
- 会话与用例：从调用中重建一次任务，按用户意图聚类，再按成功率和出现频率排序；
- 问题定位：识别失败、循环和死路，并按根因与影响会话数归并，而不是把大量 200 响应误当作成功；
- 评测闭环：将高频用例或问题转成评测，在不同模型和 Agent harness 上重复执行，用判定规则检查回归。
这里的关键不是“采集越多越好”。产品文档说明，SDK 可以在 MCP 工具输入 schema 中加入可选 telemetry 字段，调用方填写后由 SDK 在进入业务 handler 前剥离。公开说明还指出：可自定义脱敏、重写或丢弃事件；captureTelemetry: false 可以关闭会话衍生数据采集，enabled: false 可以关闭整套采集。也就是说，先定义应该保留哪些最小信号，再决定是否接入，远比事后试图从完整对话里消除风险可靠。
先做一个最小埋点，而不是改造全部工具
对于使用官方 MCP SDK 的 TypeScript 服务，Armature 在其 HN 发布说明中给出了如下包装方式：
import { createMcpAnalyticsServer } from "@armature-tech/mcp-analytics";
import { createMyMcpServer } from "./server.js";
const server = createMcpAnalyticsServer(createMyMcpServer);
这段代码的工程含义是将现有 server 交给包装层，而非逐个重写业务工具。不过，是否安装、包版本、初始化选项和实际部署位置，都应以团队接入当日的官方文档为准；不要根据“几行接入”的宣传推断数据策略或权限模型。
建议先选一个低风险但足够典型的流程，例如“查找客户后创建草稿单据”，并为它明确成功条件。第一周的目标不是优化模型，而是收集以下可行动信息：Agent 最常走的三条路径、发生循环的工具组合、最常见的失败前置条件，以及工具说明与真实参数之间是否存在歧义。
之后再检查两个容易被忽略的边界。第一，仪表盘出现的“意图”并不等于完整聊天记录；产品方在 HN 讨论中说明，它不能看到真实聊天历史或记忆，而是依赖与当前任务有关的简短意图。第二，脱敏和保留期仍是产品与合规决策：即使平台默认扫描 PII 与密钥，团队也应审阅字段白名单、删除流程、访问角色及自己的数据处理义务。
用真实故障设计评测，而不是只测工具能否返回
当分析发现“退款”相关请求经常被搜索工具漏掉，修复不应止于改一个关键词。应把这个场景转为可判定任务，并比较修复前后的接口条件。一个实用的任务可以这样写：
目标：为指定订单发起部分退款，并返回退款金额与状态。 通过条件： - 找到与订单匹配的退款入口； - 使用正确的金额与订单标识发起请求； - 输出可供用户核对的退款状态； - 失败时指出缺少的权限或参数，而不是无限重试。
Armature 的评测模型是让真实 Agent 端到端运行，再由 judge 按团队定义的条件评分。评测时要避免一次改多个变量：保留同一任务、同一服务版本和相同权限环境，建立“原始 Agent”基线；第二个 treatment 只增加新的工具描述、CLI 帮助文本或 MCP 资源。若同时改 schema、文档和模型，就算分数上升，也无法知道哪项改变真正减少了摩擦。
同时不要只看通过率。对于同样通过的两组运行，仍应比较循环次数、调用次数、耗时和代价。对 Agent 接口而言，能完成任务但需要十次探索，往往意味着后续会在限流、成本或复杂任务中暴露问题。把高频问题转化为回归样例，才能让一次修复成为持续的接口质量门槛。
建立一份可维护的 Agent 接口质量清单
把分析接入后，最容易出现的新问题是团队只盯着仪表盘，却没有把发现变成工程动作。可以为每个高频用例维护一份很小的质量清单，并让它随接口版本一起进入 PR：
- 目标是否唯一：一句任务描述最好只对应一个可验证的业务结果。若“创建客户并订阅并开票”经常失败，应先拆开确认 Agent 卡在发现客户、权限还是开票参数。
- 工具是否可发现：工具名、描述和参数是否让 Agent 能区分“搜索”“预览”“执行”？失败信息是否给出下一步，而不是只有泛化的 400 或 403？
- 副作用是否受控：对退款、删除、发送或写入等操作，是否提供预览、确认、幂等键或明确的 dry-run 路径？这既降低真实运行的风险，也让评测可以在安全环境中断言行为。
- 评测是否覆盖修复原因：如果问题是分页导致输出被截断，判定条件就要检查完整结果与页序；若问题是权限范围不清，判定条件要检查失败是否可解释。只验证最终“成功”会漏掉同类摩擦。
清单不需要追求一次覆盖所有任务。更有效的节奏是每周从问题排行中挑一个影响面大、可复现的条目：先读取 trace，写出最小任务和通过条件，在固定基线下运行少量重复试验；改完接口或文档后再用同一任务复跑。这样得到的分数变化才有解释空间。
别把会话分析当作万能监控
Armature 的价值在于补上“外部 Agent 如何使用你产品”的反馈回路：用户不在你的 UI 中点击，客户端也不由你控制，但你的 MCP/CLI 仍需像产品界面一样被观察、迭代和测试。它尤其适合提供开发者 API、支付、数据或企业工作流接口，并且已经收到难以从工单中复现的 Agent 失败反馈的团队。
它不是把评测结果变成绝对正确性的工具。Agent 运行具有非确定性，评测覆盖的是你选择的任务，而不是所有用户目标；分析得到的会话信号也不能代替安全审计、端到端权限测试或服务端可观测性。更稳妥的顺序是：先用最小化采集发现摩擦，再将高频摩擦固化为任务和判定条件，最后用重复评测验证接口、文档或工具设计是否真的改善。
当 MCP 成为用户进入产品的入口时，工具调用日志只是起点。真正值得持续追踪的是：用户意图是否被正确承接，Agent 是否能以合理成本完成任务，以及每次修复是否能够抵御下一次模型、提示词和接口版本变化。