在最近与同事们分享了关于 Agent 如何使用文档的发现后，最先被问到的问题之一（来自多人！）是：我们如何度量这些问题的影响？更广泛地说，我们如何知道诸如：
- 有多少 Agent 在尝试访问我们的文档时遇到了问题？
- 有多少文档页面受到这些问题的不利影响？
- 我们如何将 Agent 访问问题与开发者/产品成果联系起来？
这些问题有很多方面，我们仍在讨论答案可能是什么样子。但前两个问题看起来立即可以解决，所以我们可以马上开始研究这些事情。
1、有多少 Agent 在尝试访问我们的文档？
"Agent 尝试访问我们的文档"意味着什么？
许多人告诉我 Mintlify 的这个统计数据："50% 的流量来自 Agent。"这篇 Mintlify 文章 介绍得更详细一些，但关于他们如何度量这个的信息不多。我理解------Mintlify 是一个平台公司，这些信息是他们试图卖给客户的商业机密的一部分。但不知道他们具体如何追踪这个数据，很难真正深入研究这个统计数字。这个数字对我来说似乎偏高，我在想他们是否把所有 AI 相关的流量都归入了这个类别。
所以在讨论我对如何度量 Agent 流量的看法之前，对于本文，我将 AI 流量视为三个不同的类别：
- 来自收集数据训练模型的网络爬虫的流量。我在最近的文章 LLM 与 Agent 作为文档消费者 中更详细地讨论了这个问题
- 与 AI 答案引擎相关的流量。像 ChatGPT 和其他 AI 答案引擎有扫描网络获取新鲜内容的机制，以保持用户答案的更新。我还没有真正将此视为一种独特的模式，但我认为它与模型训练和 Agent 不同
- 与 Agent 实时代表用户执行任务相关的流量。我在这一领域的大部分关注点都在编码 Agent 上，如 Claude Code、GitHub Copilot 和 Cursor，但它们不是唯一可能实时访问你的文档来帮助用户执行任务的 Agent。
根据我目前看到的情况，我相信如果你把这三个类别合并为"AI 流量"------那可能达到 50%。但我很难认为第三个类别------我在这里关注的------实时代表用户执行任务的 Agent------占总流量的 50%。这完全是我基于有限样本量的直觉判断------我没有 Mintlify 作为平台公司所拥有的那种跨客户数据，所以我看不到他们看到的模式------但我也理解平台公司想要卖给你服务的现实是强调让你想购买那些服务的数据。
我在这个问题上没有利益关系。我只是专注于帮助文档团队理解 Agent 访问模式可能如何影响文档消费、产品理解和客户影响。
说完这些------以下是我对文档团队如何开始度量 Agent 尝试访问文档的看法。
2、度量对 Agent 友好内容的流量
在我看来，第一个也是最简单的选择是度量对 Agent 友好内容的流量。你的 llms.txt 获得了多少次访问？如果你已经在以 markdown 格式提供文档，这些 markdown 页面获得了多少次访问？
我最初的假设是这些流量几乎 100% 来自 Agent。但在与我们的文档平台团队交谈并看到一些实际数字后，情况比我预期的更模糊。有几种方式非 Agent 流量最终会出现在你的 markdown 页面上：
- 你的 llms.txt 充当所有爬虫的发现机制，而不仅仅是 Agent。任何找到你 llms.txt 的训练爬虫或搜索引擎机器人都会跟随这些 markdown 链接。
- 搜索引擎擅长模式发现。如果它们找到一个
.mdURL，它们可能会在其他已知路径上尝试该模式，即使这些 URL 不在你的站点地图中。* 如果有人链接到你的 markdown 页面（博客文章、README、Stack Overflow 答案），爬虫会跟随这些链接。 - 一些开发者在快速扫描 API 签名或复制代码示例时确实更喜欢阅读原始 markdown。
- 如果你的服务器支持内容协商，一些客户端发送请求
text/markdown的 Accept 头，这些请求可能会显示为 markdown 流量，即使客户端没有请求显式的.md路径。
所以 markdown 流量是 Agent 活动的信号 ，而不是指标。它可能严重偏向非人类消费者，但"几乎 100% Agent"的说法太强了。比例将取决于你的 markdown 页面的可发现性、你的 llms.txt 是否被爬取，以及有多少外部链接指向你的内容的 markdown 版本。
话虽如此，我仍然认为这是我们拥有的更好的代理之一。人类用户绝大多数浏览文档页面的 HTML 版本，所以 markdown 流量至少是一个有用的指标，表明除了典型人类用户之外的某些东西正在访问你的内容。
3、度量特定用户代理的流量？
当我在工作中开始推广这些东西时，我们文档平台团队的负责人联系我，一起头脑风暴我们还可以看什么来度量流量。我们的 DOP（文档平台）团队已经在使用已知的用户代理字符串追踪一些形式的 AI 流量，再加上一些有根据的猜测。
如果你不熟悉用户代理，看看 Mozilla 的参考，但简要说明是：它是伴随访问网站服务器内容请求的标识符。Web 浏览器通常通过在请求头中传递的用户代理以某种方式标识自己。从历史上看，这与获取为特定浏览器优化的内容有关。但一旦人们发现某些 浏览器比其他浏览器获得"更好"的内容，他们就开始故意发送错误的用户代理字符串来获取"更好"的内容。现在用户代理字符串因各种原因被普遍误用，所以它充其量是一个不精确的标识符。
但有时，不精确的信号比完全没有信号好。
在我早期与 Claude 的探索中，Claude 做了一些初步研究（在网络上阅读内容），发现 Agent 平台通常不发送可识别的用户代理。与用于模型训练或答案引擎目的的 AI 网络爬虫不同------那些有时发送准确的用户代理字符串------Agent 平台与人类用户无法区分。
我想深入研究，看看这有多真实。所以我做了一些测试！
我会尝试写一篇关于实验本身的完整文章，因为像往常一样，我得到了一些意外，但这里我们的简要说明是：
-
我手动测试了我现在可以访问的三个 Agent 框架的 Web 流量：Claude Code、GitHub Copilot（通过 VS Code）和 Cursor
-
我让这些 Agent 访问一个我拥有且可以看到服务器日志的网站 URL
-
我用非常中立的提示让它们访问网站，然后阅读网站的特定页面（没有提到 llms.txt 或 markdown 页面）
-
我观察了在 Agent 框架中可以看到的 Web 获取行为，在观察到意外时提问以深入了解细节
-
我在 Agent 执行访问时同时 查看服务器日志，以查看服务器上发生了什么
其中一个工具，GitHub Copilot，发送了一个乍一看像正常浏览器流量的用户代理字符串：Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Code/1.109.5 Chrome/142.0.7444.265 Electron/39.3.0 Safari/537.36
如果你知道要找什么，你可以在字符串中发现 Code/ 和 Electron/，这将它标识为 VS Code 而不是普通浏览器。但如果你只是在服务器日志中扫描明显的机器人流量，这与正常用户完全融合在一起。
它似乎使用的是基于浏览器的获取工具，因为请求立即触发了浏览器会请求的 CSS 和其他资产的相关请求。Agent 不需要 这些资产，但浏览器引擎会自动请求它们，所以次要请求的发生不需要 Agent 做任何特别的事情来产生它们。这只是 GitHub Copilot fetch_webpage 工具实现方式的一个功能。
查看网站第二页的请求始终在第一个请求后的 15-20 秒内发出。我推测 Agent 请求可能来得太快，不可能是人类请求，所以如果 Agent 在第一个请求几秒内请求第二页，来自相同 IP 地址和用户字符串的第二个请求"太快"而不可能是人类，可能表明是 Agent。但大约 20 秒对人类来说太快了吗？我真的不知道。所以我不认为我们可以自信地依赖这一点，尽管我们可能将其视为"信号"而不是"指标"的启发式方法。
对于另外两个 Agent，它们使用 HTTP 访问库而不是基于浏览器的工具有意义------Agent 不需要 CSS 资产，有人可能会争辩说 GitHub Copilot 的实现是浪费的。Claude Code 和 Cursor 都使用了相同的 HTTP 访问库，尽管它们是不同版本。如果我昨天有大量指标，我会查找那些 HTTP 访问库，根据我从每个 Agent 观察到的版本追踪，我就可以告诉你我们收到了来自 Claude Code 或 Cursor 的多少流量。但那些版本会变化，所以那一天的快照并不是世界的稳定状态。
我还观察到一个情况，GitHub Copilot 由于它称之为"环境变量和瞬时问题"------即间歇性的不稳定性------在访问网站时遇到了一些麻烦，于是它转向了一个 Python HTTP 访问库，并通过 Python 库获取了站点数据。所以现在有两个需要注意的东西用于 GitHub Copilot------类浏览器的用户代理字符串，或 Python HTTP 访问库用户代理。然后我们面临的问题是：这源自模型数据，还是来自 Agent 框架的提示？如果我通过其他 Agent 平台使用 GPT 5.3，在不稳定性事件中它是否会做同样的事情？我不知道！所以我们不能必然假设 Python HTTP 访问是 GitHub Copilot 的把戏------也许它是可能反映任何 Agent 平台的通用 LLM 变通方法。
所以当涉及用户代理时，我不认为我们可以可靠地将特定用户代理字符串与特定 Agent 平台关联起来。但有 我们可以寻找的模式，这些模式可能是通用的"Agent"------现在可能这就足够了。
（唉，这么多限定词！）
4、有多少 Agent 遇到了问题？
如果我们有办法度量 Agent 流量，即使它是模糊的，下一个问题是：有多少 Agent 遇到了问题？
这就是事情变得棘手的地方。从我的 Web Fetch 探索 中我知道，截断限制因平台而异。Claude Code 在大约 100KB 文本处截断。其他平台大概也有限制，但大多数不会说是什么。如果我们能可靠地将特定用户代理字符串与特定平台关联起来，我们可以看看从每个平台获得了多少访问，将这些与已知的截断限制关联起来，并开始三角测量可能在给定页面上遇到问题的 Agent 比例。
但正如我上面所说的，将用户代理字符串与特定平台关联充其量是不可靠的。所以与其试图识别哪个 平台在访问你以及那个平台的截断限制是否是问题，我认为更实用的方法是从你的内容反向工作。
你知道你的页面大小。你可以度量每个页面作为序列化 HTML 的字符数，如果你提供 markdown，也度量 markdown 的字符数。从有限的可用数据中你知道截断限制往往在 5K-150K 字符范围内，具体取决于平台和工具实现。所以如果一个页面是 300K 字符的 HTML 和 80K 的 markdown，你可以相当确信大多数访问 HTML 版本的 Agent 正在获取截断的内容，而一些访问 markdown 版本的 Agent 可能也是（取决于它们的特定限制）。
这是一个不完美的启发式方法。但它让你可以识别可能 造成问题的页面，而不需要解决将流量归因于特定平台这个更难的问题。如果一个页面是 20K 字符的干净 markdown，它对几乎所有 Agent 来说可能都没问题。如果是 400K 字符带内联 CSS 的 HTML，它可能对每个 Agent 都坏了。你不需要知道哪个 Agent 是哪个就知道这一点。
5、有多少文档页面受到这些问题的不利影响？
你可以从两个方向来处理这个问题。
按流量切片。 如果你在提供文档页面的 markdown 版本，你可以查看哪些页面获得了最多的 markdown 访问。这些可能是你的非人类访问最多的页面，它们是值得首先审计的页面。如果一个页面获得了大量 Agent 流量并且超过 100K 字符，那就是 Agent 几乎肯定在获取不完整内容的页面。
按内容切片。 或者，你可以整体查看你的文档并问：我们的页面中有多少超过了合理的截断限制？这是我推荐用于初始审计的方法。不要手动做。写一个脚本来爬取你的文档页面并度量每个页面的字符数，包括 HTML 和 markdown（如果你提供的话）。你可能会发现一个分布：一堆没问题的页面，以及一个过大的页面长尾。
如果你在使用 afdocs，页面大小检查已经标记超过可配置阈值的页面。指向你的文档，你会得到一个按风险排序的页面列表。这是一个起点，不是最终结论，但它让你在几分钟内从"我们完全不知道"到"这里是 50 个最可能造成问题的页面"。
如果你根本不提供 markdown？那么诚实的答案是 100% 的文档页面都可能受到这些问题的不利影响，因为 HTML 页面携带了所有 CSS 和 JavaScript 开销，这些开销在 Agent 看到你的内容之前就消耗了截断预算。即使你确实提供了 markdown，个别页面可能仍然太长，或者有结构问题，如扁平化的标签内容，使序列化版本比人类在渲染页面上看到的大得多。提供 markdown 是必要的但不是充分的。
6、度量 → 影响？
到目前为止我讨论的一切都是度量。但度量不等于影响。知道你 40% 的文档页面超过 Agent 截断限制是有用的信息，但它不告诉你是否有人关心那些页面。影响是下游后果：失败的任务、放弃的注册、困惑的开发者、损失的收入。
这是最难度量的部分，老实说，我不认为有人有好的答案。故障模式很大程度上是不可见的。开发者的 Agent 无声地获取截断的内容，产生错误的答案，然后开发者要么自己弄明白了（浪费时间），要么没弄明白就发布了有问题的东西，要么放弃了并转向了有更好文档的竞争对手。这些结果中的任何一个都不容易追溯到"Agent 无法阅读你的文档页面。"
但即使没有完美的归因，你也可以做出一些战略决策。首先识别哪些页面对你的业务最重要。你的快速入门指南、认证文档、计费 API 参考、迁移指南：这些是糟糕的 Agent 体验最有可能让你失去客户的页面。如果这些页面超过了截断限制，那就是你应该首先集中修复工作的方向。
修复工作本身并不简单。将长页面分解为适合截断限制的较短页面，重构标签内容使最常见的用例在源顺序中排在最前面，为还没有 markdown 版本的页面添加 markdown 版本：所有这些都需要时间和精力。如果你只能修复一些页面，就修复那些对你的业务最重要的页面。一个 Agent 实际能阅读的快速入门指南比每月只有 10 次访问的利基参考页面更有价值。
我还觉得这里有一个机会，让文档平台和分析工具开始连接这些点。如果你能将 Agent 流量模式与开发者旅程指标（注册完成、首次 API 调用、达到"hello world"的时间）关联起来，你就能开始看到影响的轮廓。我们还没到那一步。但我在本文中描述的度量工作是当那些工具最终存在时你需要在其上构建的基础。