当 AI 代理是您最频繁的调用者时，API 可观察性

您的 API 仪表板显示凌晨 3 点流量激增 4 倍。 没有营销活动。 没有产品推出。 没有黑客新闻 帖子。 AI 代理通过 MCP 服务器发现您的端点并开始运行多步骤安全性 审计； DNS 查找、SSL 检查、标头分析、每 10 分钟 2 秒突发 15 个端点。

现在这很正常。 Gartner 预计 30% 或更多的 API 需求增长将来自 LLM 支持的代理 2026 年。思科的一项调查发现，89% 的组织已经监控生产中的代理行为。 的 交通就在这里。 问题是你的可观察性堆栈是否可以区分人类和人类 开发人员在凌晨 3 点测试端点和运行 12 步骤工作流程的代理。

传统的 APM 工具聚合每个端点的指标。 他们向你展示了 /v1/dns/lookup 得到了 500 过去一小时内的请求，但他们不会告诉您其中 480 个来自 40 次代理运行，每次调用 以可预测的顺序进行 DNS 查找、SSL 检查和标头分析。 这个盲点会让你付出代价； 你不能 设置适当的速率限制，您无法调试代理故障，也无法预测基础设施成本。

五种模式可以解决这个问题。 每一项都解决了标准 APM 提供的内容与您提供的内容之间的特定差距 当客服人员是您最常打电话的人时需要。

为什么传统 APM 会错过座席流量

人类开发人员调用一个端点，读取响应，也许几分钟后调用另一个端点。 AI 代理快速连续调用 5 到 15 个端点，以编程方式解析每个响应，然后重试 失败时，转移到下一个工作流程。 这两种流量形状在每个端点上看起来相同 级别，但在对运营重要的各个方面表现不同。

Datadog、New Relic 和 Grafana 向您显示每个端点的延迟百分位数和错误率。 他们不 向您展示“代理运行 #a3f7 依次调用 8 个工具，在工具 6 上失败，重试 4 次，然后烧毁 通过 35 次 API 调用来完成原本需要 8 次的任务。” 为此，您需要专门构建的跟踪。

模式 1：检测代理呼叫者

在观察代理流量之前，您需要对其进行识别。 三个信号一起工作： 用户代理字符串、请求节奏和显式标头。

用户代理匹配

代理框架设置可识别的用户代理字符串。 LangChain、CrewAI、AutoGen 和 Anthropic SDK 所有这些都在其默认标头中包含框架名称。 SDK 生成的来自库的请求，例如 axios, node-fetch， 和 python-requests 也发出非浏览器信号 交通。

请求节奏检测

人类不会在 5 秒内调用 4 个不同的端点。 服务器端节奏检测器标记客户端 在短时间内击中多个唯一端点：

全检测中间件

将这两个信号组合到一个中间件中，将每个请求标记为代理或人类。 该标签流入 您的日志记录、指标和速率限制层：

这 X-Agent-Detected 响应标头可让代理开发人员确认他们的请求 被正确分类。 置信度级别会纳入您的警报规则中； “高”信心 检测（显式标头）是确定的，而“中”（UA 匹配）可能需要节奏确认。

模式 2：使用 OpenTelemetry 跟踪多工具链

代理调用 botoi 的 MCP 服务器来审核域将命中 /v1/dns/lookup， 然后 /v1/ssl-cert/certificate， 然后 /v1/headers 几秒钟之内。 标准中 APM，这是三个独立的、不相关的请求。 与共享 X-Agent-Run-ID 标头 和 OpenTelemetry 跨度，它们成为一个可追踪的工作流程。

每个代理工作流都有一个父跨度。 每个工具调用都会成为嵌套在其下的子范围。 在 Jaeger、Grafana Tempo 或任何 OTEL 兼容后端，您会看到完整的链：DNS 查找花费了 45 毫秒， SSL 检查花费了 120 毫秒，标头花费了 30 毫秒，总工作流程时间为 210 毫秒。 当 8 个工具中的第 6 个失败并且 代理重试 4 次，您可以在跟踪中看到它，而不是通过单独的端点日志进行搜索。

模式 3：突发工作负载的速率限制

固定窗口速率限制惩罚代理。 代理在 2 秒内发送 15 个请求来完成一次 工作流程，然后沉默 58 秒。 “每分钟 60 个请求”的固定窗口已经足够了 空间，但“每 5 秒 5 个请求”的固定窗口会阻止代理处理请求 6，即使 尽管持续率远低于极限。

令牌桶解决了这个问题。 存储桶容量控制突发大小（代理可以处理多少个请求） 突发火灾），再填充率控制持续吞吐量（桶恢复的速度）。 映射到代理如何工作的两个参数。

关键见解：代理需要更高的突发容量和相当的持续速率。 人类用户 使用 5 个令牌的桶和 0.5 个令牌/秒的填充率可以发出 5 个快速请求，然后每个请求一个 2秒。 具有 20 个令牌桶和 2 个令牌/秒填充的代理可以触发 15 个端点工作流 一次突发，并在 10 秒后将桶重新装满以进行下一次运行。

这就是 botoi 的 API 处理混合流量的方式。 匿名请求（无 API 密钥）每分钟突发 5 个请求 每天上限为 100 个请求，由 IP 跟踪。 付费计划的经过身份验证的请求使用 Unkey 的令牌桶 处于每层具有更高突发和持续限制的边缘。

模式 4：使用相关标头记录工具使用上下文

请求 /v1/dns/lookup 孤立地看，你无法得知任何有关意图的信息。 相同的请求 8 步安全审核的第 1 步告诉您一切。 相关标头弥补了这一差距。

两个标头包含您需要的所有上下文：

• X-Agent-Run-ID：将所有请求分组到单个工作流程中的 UUID
• X-Agent-Tool-Index：此调用在工具链中的位置（1、2、3...）

在客户端，代理将两个标头附加到工作流中的每个请求：

在服务器端，您可以记录每个请求的两个标头。 重建代理所做的事情变成 单个查询：“向我显示所有请求 X-Agent-Run-ID = abc-123 订购者 X-Agent-Tool-Index” 没有时间戳关联，没有 IP 匹配，没有猜测。

如果您的代理使用 botoi 的 MCP 服务器，则 MCP 协议已将工具调用分组到会话中。 的 MCP 服务器位于 api.botoi.com/mcp 通过标头转发 API 密钥，您可以扩展 它传递一个在所有 49 个可用工具中持续存在的运行 ID。

模式 5：针对特定于代理的异常发出警报

标准警报针对 HTTP 错误率和延迟百分位触发。 特定于代理的警报已启动 行为模式表明代理本身有问题，而不是您的 API。

三种警报类型捕获最常见的代理故障：

• 意外的工具顺序： 代理在 DNS 查找之前调用 SSL 检查，表明代理的规划步骤中存在逻辑错误
• 检测到重试循环： 一次代理运行后，同一端点在 10 秒内被命中 5 次或更多次，表明代理未读取错误响应
• 成本飙升： 代理运行超过 50 个 API 调用，这意味着循环或幻觉正在导致消耗失控

重试循环警报是最高值的信号。 代理收到 400 错误（错误输入）并且 重试同一请求 20 次会超出速率限制并且不会产生有用的输出。 捕捉 只需几秒钟而不是几分钟，即可节省您的基础设施预算和代理运营商的预算 API配额。

组合在一起：混合流量的可观察性堆栈

这是涵盖所有五种模式的堆栈：

如果您已经为 API 运行 Datadog 或 Grafana，则无需替换它们。 添加 OTEL 仪表层位于顶部，将代理标记的跟踪传送到专用仪表板，以及 根据代理特定的属性构建警报规则。 现有的每个端点指标保持不变 对于基础设施监控很有用。 新的代理感知跟踪可以回答您的问题 值班工程师在凌晨 3 点询问：“该代理在做什么，为什么要重试，我是否应该这样做？” 挡住吗？”

要点

• 首先检测，其次观察。 将每个请求标记为代理或人类使用 用户代理模式、节奏检测和显式标头。 下游的一切都取决于 关于这个分类。
• 跟踪工作流程，而不是端点。 代理的工作单元是一个多功能工具 链，而不是单个 API 调用。 OpenTelemetry 父/子跨度使代理工作流程 跟踪后端中的一流对象。
• 固定窗口上的令牌桶。 特工爆了。 令牌桶容纳突发 同时执行持续的限制。 将铲斗容量与您预期的最长工具链相匹配。
• 相关标头便宜且功能强大。 X-Agent-Run-ID 和 X-Agent-Tool-Index 将不透明的请求日志转变为可读的代理工作流程 使用单个数据库查询。
• 针对行为而非音量发出警报。 重试循环、意外的工具排序以及 失控的呼叫计数可以在真正的问题变成事件之前发现它们。

Botoi 的 API 可处理 150 多个端点和包含 49 个工具的 MCP 服务器的人员流量和代理流量。 每个回复都包含 X-RateLimit 标头。 如果您正在构建一个可以调用的代理 外部 API，传递一个 X-Agent-Run-ID 标头，遵守速率限制标头，并且 向您的 API 提供商提供他们保持代理平稳运行所需的信号。 尝试一下 交互式 API 文档 或通过连接您的AI助手 MCP服务器 去看 这些模式在实践中。