文档明明更新了，AI为什么还在生成三年前的SDK写法？

摘要：Microsoft公开的Agent Experience方法指出，Agent生成旧SDK、过时认证方式或错误脚手架，并不总是模型本身的问题。测试团队要沿着“发现—加载—调用—应用”轨迹定位，才能知道该改文档、扩展、示例还是模型提示。

Microsoft在2026年10月公开Agent Experience（AX）实践手册时，描述了一个非常现实的现象：Coding Agent会选错SDK版本、采用废弃认证方式，或者生成产品团队并不推荐的初始化方案。其公开评测覆盖Cosmos DB、SPFx等技术，并把改进落实到文档和Agent扩展；官方称Cosmos DB Agent Kit因此完成了46项改进。

这不是“模型偶尔胡说”的另一种包装。开发者越来越多地让Agent选择SDK、版本和实现方式，Agent生成的体验会反过来影响开发者对产品的判断。如果官方文档最新，但搜索索引、代码样例、脚手架默认值或扩展说明仍指向旧版本，模型只是把这些冲突放大了。

先把失败拆成四段轨迹

测试一个“请用当前SDK创建订单查询服务”的任务，不要只比最终代码。至少记录四个问题：

1. 发现：Agent是否找到了正确文档、Skill或扩展；
2. 加载：材料是否真正进入上下文，版本与依赖是否明确；
3. 调用：Agent是否调用了对应工具，参数是否正确；
4. 应用：已经拿到正确信息后，是否仍用错API或认证模式。

这四类失败对应完全不同的修复。没有发现，应改入口、命名和检索；发现但没加载，应检查上下文预算和触发条件；加载但没调用，应改工具描述和工作流；调用后仍应用错误，才更可能需要改示例、标准或模型侧提示。

构造一个初级测试也能复现的用例

准备两个本地文档片段：v1使用ApiKeyCredential，v2要求TokenCredential并废弃旧构造器。让Agent完成同一个订单查询任务，分别运行四组环境：只有v1、只有v2、两版同时存在、v2存在但文件名写成draft-new。

不要只断言项目能启动，还要检查来源与版本：

def assert_agent_used_current_sdk(trace, files):
    assert "sdk-v2/authentication.md" in trace["retrieved_docs"]
    assert "ApiKeyCredential(" not in files["client.py"]
    assert "TokenCredential(" in files["client.py"]
    assert trace["selected_version"] == "v2"

反常结果往往出现在“两版同时存在”：Agent引用了v2解释，却复制v1代码；或者编译依赖被锁定在旧版本，导致旧写法仍能通过。此时单纯升级模型无法解释根因，Trace才会告诉你冲突来自检索、依赖还是样例。

评测标准不要再让Agent自己写完

Microsoft AX材料特别提醒，写criterion是最难的环节，也要警惕完全让模型代写标准。因为同一个Agent如果误解了“当前推荐方式”，它可能同时写出错误代码和一条能让错误代码通过的评分规则。

测试团队可以先定三条确定标准：必须使用指定主版本；不得出现废弃API；认证信息不得硬编码。再加两条语义标准：生成的说明是否解释迁移原因；失败时是否提示兼容边界。前者用代码评测，后者用经人工校准的Judge评测。

版本变化后，固定重跑四类样本：全新接入、旧项目升级、相互冲突的文档、缺失依赖的异常路径。把生产中发现的旧写法反向加入离线集，形成“真实错误—资料修复—同任务复跑”的闭环。

真正的新测试对象是产品的“可被Agent理解性”

以前测试文档更多关注人能否读懂。现在还要检查机器能否找到正确入口、区分版本、理解弃用关系、调用工具并把建议落到代码。一个产品对人友好，不等于对Agent友好；文档完整，也不等于上下文没有冲突。

测试团队可以从最小实验开始：挑一个你们近期更新过的API，保留新旧材料，让两个Coding Agent各跑五次。不要先比较谁写得快，先把失败归到发现、加载、调用、应用四段。你会更快知道该修模型，还是该修产品交给Agent的知识表面。

场景不能只写“请使用最新版”

AX评测最容易写成提示词比赛：在任务里直接告诉Agent版本号、认证类名和正确文档路径，结果自然很好看。但真实开发者往往只会说“帮我接入订单SDK”。评测应保留这种信息不完整，并观察产品是否能让Agent发现正确做法。

一组有效场景可分为四档：零上下文的新项目；依赖旧版本的升级项目；新旧文档同时存在的冲突项目；网络受限、扩展加载失败的异常项目。每档都要保存初始仓库，保证不同模型和版本从同一起点运行。

还要避免把某次成功写成标准答案。Agent可能使用官方允许的另一种认证流程，只要满足版本、安全与可维护性规则就应通过。criterion应该描述行为与约束，而不是复制一份唯一代码。

从症状到修复要做对照实验

如果Agent没有加载扩展，不要同时修改文档、工具名和系统提示。每次只改一个变量：先调整入口描述，重复运行；再调整触发词；最后才补Prompt。否则结果改善后无法知道哪个修复有效，也无法把经验迁移到其他SDK。

对照实验至少记录成功率、错误类型、调用轨迹、输入令牌、延迟和生成代码的业务门禁。某种修复可能让Agent更常找到新文档，却增加上下文并导致后半程忽略关键约束。只看最终成功率会漏掉这种交换。

把资料本身也纳入发布门禁

SDK发布不应只跑包测试，还要跑“Agent消费测试”。新版本文档合并后，用固定任务检查：搜索是否优先返回当前版本；代码块能否独立运行；弃用API是否清晰指向替代方案；脚手架是否锁定最新兼容版本；扩展是否加载；Agent生成代码是否通过安全与业务规则。

失败时不要立刻改模型。若多个模型都引用同一旧页面，优先处理信息架构；若只有某个Agent不触发工具，检查集成；若所有材料正确但应用仍错，再评估模型与提示。

线上还会出现“文档修好了，缓存没更新”

生产环境常有搜索索引、向量库、CDN、IDE扩展和本地缓存。官网页面已经更新，不代表Agent看到的是同一版本。Trace应记录文档内容哈希与索引时间，而不是只记一个URL。模型回归若命中旧哈希，问题就能从“AI又犯错”缩小到缓存或同步链路。

测试矩阵也要覆盖灰度：一部分用户收到新扩展、一部分仍是旧版；旧项目锁文件与新文档不兼容；不同地区镜像更新时间不同。AX不是额外的营销体验，而是一条真实的版本一致性测试线。

判断修复是否值得发布

改善Agent表现可能需要改文档、示例、脚手架或扩展，任何一项都可能影响人类开发者。最终验收应同时看：Agent错误是否下降；人工读者是否更容易理解；旧版本用户是否仍能找到兼容说明；是否引入新的歧义；维护成本是否可接受。

测试团队在这里承担的是双重用户视角：人如何使用产品，Agent如何代理人使用产品。两者都能正确到达当前推荐路径，才叫真正修复。

本文部分内容参考了霍格沃兹测试开发学社整理的相关技术资料，主要涉及软件测试、自动化测试、测试开发及 AI 测试等内容，侧重测试实践、工具应用与工程经验整理。