为新受众重新发现快速参考:代理
我最近给 API 文档新增了一种文档格式,不过多少有点偶然。这种格式叫快速参考页,它以精简的方式列出一套 API 的所有关键信息。
举个例子:这是 Places (New) 快速参考,另外还有 Routes 和 Maps JavaScript 的版本。站上每个产品(将近 60 个)都有一个类似的快速参考页,通常位于 /quick-reference 路径下。
如果你长期关注我的博客,可能还记得我曾多次赞美过快速参考指南——不止一个作品集,还写了很多 posts 来推崇这种形式,比如这篇:快速参考指南:技术写作的诗歌。
快速参考指南是我做过的唯一让 PM 感动落泪的交付物。不过到了 2022 年,我把它列入了已经放弃的趋势,因为入门教程更契合开发者文档的需求。
快速参考页或许正迎来新的受众——AI 代理。我先说明页面的内容构成及其格式由来,再解释代理如何检索内容,以及我认为快速参考在哪些方面对它们有帮助。
快速参考页包含什么
快速参考页篇幅简短,几乎全由列表组成,不包含代码示例。页面分为以下几个部分:
- 产品关键信息: 产品名称、别名、支持的平台、发布阶段及区域可用性。
- 适用场景: 包括“何时使用”和“何时不应使用”两个列表。后者会指向更合适的产品,例如 Android 平台的 Places SDK 或 Maps JavaScript API。
- 配置步骤: 需要启用的服务、认证方式、客户端库包,以及定价、政策文档和发布说明的链接。
- 相关产品: 该产品替代的旧版 API,以及开发者常与之配合使用的其他 API。
- 常见错误: 每个条目包含问题、修复方法及链接。例如,一个条目涉及缺失的 field masks,另一个涉及被遗漏或重复使用的 autocomplete session tokens。
- 可执行的操作: 功能能力列表,每项任务都链接到相应的说明页面或章节。
这些信息大多已存在于文档的某个角落。快速参考将它们汇总到同一页面,并链接至详细信息处。换言之,该页面更像是一个路由页,而非教程。
为何该格式可能适合代理
当代理开始处理任务时,在编写代码前需先回答几个问题:哪个产品适合该任务?是否有比其训练数据中版本更新的 API?开发者在使用该 API 时常犯哪些错误?详细指南在哪里?
常规文档也能回答这些问题,但答案分散在概述、迁移指南、故障排除页面和发布说明中。快速参考将答案集中在一页上,各章节短小,便于放入单个数据块中。
这种格式的几个细节,对检索的作用可能比看上去更大。比如每个标题都会重复产品名称,像"Places API (New): common mistakes"这样。对人来说,这种重复显得多余。但正如我在 Chunking your content for agent readability 一文中提到的,内容分块后可能脱离上层标题单独送达,此时区块标题或许就是唯一能说明该内容属于哪个产品的文字。
"don't use when"(不适用场景)列表也是常规文档很少包含的内容。产品文档通常只讲产品能做什么,很少劝你去用别的产品。但对一个需要在 web service、Android SDK、iOS SDK 和 JavaScript API 之间做选择的 agent 来说,这份列表可能是页面上最有价值的部分。把负面边界写得明明白白,或许就是面向 agent 写作时值得采纳的新惯例之一。
此外,common mistakes 部分还包含具体的错误名称,比如 LegacyApiNotActivatedMapError,这样 agent 在按错误信息搜索时就有内容可以匹配上了。
这种格式是如何诞生的
这种格式差不多是我无意中摸索出来的。一位同事为每个产品整理了一份 capabilities(能力)清单,也就是产品允许你完成的那些事情,并用这些数据做了一个 capabilities explorer。通过这个工具,你可以从手头的任务出发,找出哪些产品具备相应的能力,还能按平台筛选,比如 iOS、Android 或 web。
所有这些能力信息都集中在一个 JSON 文件里,遵循预定义的结构。随着产品越来越多,这个 JSON 文件也不断膨胀,最终超过了 15000 行。如果你编辑过大体积的 JSON 文件就会知道:它既繁琐又容易出错,而且很难看清整体结构。
Capabilities 信息也成为了我们 product skills 的信息源之一。当用户加载 Google Maps Platform 的入口 skill 后,系统会下载一个与其提示词场景相关的子 skill,该子 skill 会列出产品的 capabilities,并链接到文档的不同部分。
大 JSON 文件带来的挑战
这个 capabilities 文件运行良好,但存在几个问题。首先,如何让产品经理轻松地编辑他们产品的 capabilities 列表?直接编辑那个庞大的 JSON 文件并不方便。我们需要一种更好的方法。
于是,我们决定将 capabilities 文件拆分为独立的 product YAML 文件。每个产品(在这种情况下即每个 API)都有一个专属的 YAML 文件。这些产品文件遵循一个预定义的 JSON schema,包含 capabilities 以及其他产品信息,例如你在 quick reference 中看到的内容。
一个脚本会读取所有独立的产品文件,并重新组合回那个庞大的 capabilities 文件,以便它继续服务于 capabilities explorer 和其他使用它的地方。这个 capabilities 文件因此成为了下游生成物,而非唯一的 source of truth。同样的产品文件也为 quick reference 页面提供数据源。换句话说,YAML 文件充当了产品信息的“小型数据库”,其他文件可以从中提取数据。只要每个文件保持足够小以便编辑,JSON 和 YAML 存储此类信息都没有问题。
我还构建了一个可视化 YAML 编辑器(或者更准确地说,是 Gemini 构建的),让作者和 PM 能更轻松地处理 YAML 内容。我还制作了一个 skill,帮助作家处理 schema、验证内容并执行其他任务。实现中还有一些其他部分(如 presubmits、验证等),但这就是大体思路。
我不确定,即使有了可视化编辑器和 skill,非技术作者(如 PM)是否会愿意按照 schema 编辑 YAML。不幸的是,该文件仍然具有令人却步的门槛。至少,技术作家可以使用这种模式工作。现实情况是,大多数作者都会让 AI 使用 skill 进行更新,这也是我现在主要的工作方式。
Docs 和 Skills 的单一数据源
这样的设计还有一个更大的目标。我一直认为,产品技能应该从文档派生出来,而不是与文档并行存在。Agent 似乎挺喜欢技能:它们紧凑且结构化,便于 agent 使用。但团队在迭代技能内容以解决 agent 使用中的摩擦时,技能可能会逐渐演变成一个独立的信息源,而文档却被甩在后面。
一个 promising 的方向是:让技能负责更高层面的指引,比如哪个产品适合某个任务、如何组织应用,而让 RAG 检索从文档中提供具体的产品细节。这样,产品事实只需要在一处修改,所有把它传递给 agent 的路径都会同步更新。
Agent 如何发现内容
快速参考页面是一个新尝试,目前还没有在侧边栏或其他页面中添加链接。除了搜索,人类找不到它们。我原以为 agent 仍然能找到,事实也部分如此。但 agent 发现内容的方式似乎比我预想的更窄。据我观察,只有两条路径:通过 MCP 检索,以及通过网络。
通过检索(MCP)
产品技能加载时,会告诉 agent 该读哪些文件、调用哪些工具,包括如何通过 MCP 访问我们的 RAG 服务器。Agent 使用 Developer Knowledge API 调用 RAG。该 API 可以返回内容分块(searchDocumentChunks 端点)或生成式回答(answerQuery 端点)。只有安装了产品技能或 MCP 服务器的 agent 才会走这条路径。
通过网络
Agent 还有两个网络工具。第一个是网络搜索:agent 写一个查询发给搜索引擎。根据工具不同,它要么拿回一组标题、URL 和摘要片段,要么拿到一段由更小的模型基于搜索结果生成的简短总结。无论如何,agent 得到的是网络的压缩版本,混合自多个站点。这些站点可能包含第三方页面,其中复述着关于你产品的过时信息。
第二个工具是网页抓取(web fetch),更接近 curl 下载。agent 提供一个确切的 URL,工具下载页面并转换为 Markdown。Web fetch 不会搜索任何东西,只抓取 agent 手上已有的 URL,而且有些工具会在 agent 看到页面之前先经过一个更小的模型处理。
Agent 实际调用 web fetch 的频率如何?这恐怕因平台而异。就我接触过的平台而言,Agent 很少在搜索后继续抓取搜索结果所指向的页面——搜索摘要本身往往就已是答案。当 Agent 确实去抓取页面时,通常是某个 skill 指明了具体的 URL,或者用户直接在提示词中粘贴了链接。此外,Agent 倾向于在任务初期、规划阶段完成大部分信息检索,一旦确定了方案,便很少再回头搜索。
简而言之,