Skip to main content

​
电梯演讲

您提议进行什么更改？
定义代理如何将遥测（日志、指标、追踪）导出到客户端，而无需通过 ACP 传输隧道传输。客户端运行本地遥测接收器，并在启动代理时传递标准的 OpenTelemetry 环境变量。这使遥测保持在 ACP 传输之外，并使编辑器能够显示代理活动、调试问题以及与可观测性后端集成。

​
现状

今天的事情是如何运作的，这导致了什么问题？我们为什么要改变？
ACP 定义了客户端如何将代理作为子进程启动并通过 stdio 进行通信。meta-propagation RFD 通过 params._meta 解决了追踪上下文传播问题，实现了追踪关联。但是，对于代理应该如何导出实际的遥测数据（跨度、指标、日志），没有约定。 没有标准方法：
  1. 无法了解代理行为 - 编辑器无法显示代理正在做什么（令牌使用、工具调用、计时）
  2. 调试困难 - 当代理失败时，没有结构化的方法来捕获诊断信息
  3. 解决方案碎片化 - 每个代理/客户端对发明自己的遥测机制
  4. 凭证暴露风险 - 如果代理需要直接将遥测发送到后端，它们需要凭证
通过 ACP stdio 传输隧道传输遥测是有问题的：
  • 队头阻塞 - 遥测流量可能会延迟代理消息
  • 实现负担 - ACP 需要定义遥测消息格式
  • 耦合 - 代理需要 ACP 特定的遥测代码而不是标准 SDK

​
我们提议对此做什么

您提议如何改善情况？
想要接收代理遥测的客户端运行本地 OTLP（OpenTelemetry Protocol）接收器，并在启动代理子进程时注入环境变量： 
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_SERVICE_NAME=agent-name
使用 OpenTelemetry SDK 的代理会自动从这些变量配置。客户端的接收器可以：
  • 在编辑器 UI 中显示遥测（例如，令牌计数、计时、错误）
  • 将遥测转发到客户端配置的可观测性后端
  • 在转发之前添加客户端上下文
这遵循 OpenTelemetry 收集器部署模式，本地接收器将遥测代理到后端。

​
架构

┌────────────────────────────────────────────────────────────┐
│ 客户端/编辑器                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │ ACP 处理器   │    │OTLP 接收器   │───▶│   导出器     │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
└────────┬─────────────────────▲──────────────────┬──────────┘
         │ stdio               │ HTTP             │
         ▼                     │                  ▼
┌─────────────────────┐        │         ┌───────────────────┐
│ 代理进程            │        │         │ 可观测性          │
│  ┌──────────────┐   │        │         │ 后端              │
│  │ ACP 代理     │   │        │         └───────────────────┘
│  ├──────────────┤   │        │
│  │ OTEL SDK     │────────────┘
│  └──────────────┘   │
└─────────────────────┘

​
发现

环境变量必须在启动子进程之前设置，但 ACP 能力交换发生在连接之后。发现的选项：
  1. 乐观注入 - 客户端无条件注入 OTEL 环境变量。不支持 OpenTelemetry 的代理只需忽略它们。这是务实的，因为环境变量成本很低，OTEL SDK 可以优雅地处理配置错误。
  2. 注册表元数据 - 代理注册表（如 PR #289 中提议的）可以在代理清单中包含遥测支持，让客户端提前知道。
  3. 手动配置 - 用户配置他们的客户端以对特定代理启用遥测收集。

​
美好的未来

一旦这个功能存在，事情将如何发展？
  1. 编辑器集成 - 编辑器可以显示代理活动：令牌使用、工具调用计时、模型切换、错误
  2. 统一调试 - 当代理失败时，结构化遥测可用于诊断
  3. 端到端追踪 - 结合 params._meta 追踪传播，追踪从客户端流经代理到任何下游服务
  4. 无需凭证共享 - 代理永远看不到后端凭证；客户端处理身份验证
  5. 标准 SDK - 代理作者使用在任何上下文中都能正常工作的普通 OpenTelemetry SDK，而不是 ACP 特定的代码

​
实施细节

告诉我更多关于您的实施。您的详细实施计划是什么？

​
1. 创建 docs/protocol/observability.mdx

添加新的协议文档页面，涵盖 ACP 的可观测性实践。此页面将描述： 对于客户端/编辑器：
  • 运行 OTLP 接收器以收集代理遥测
  • 在启动代理子进程时注入 OTEL_EXPORTER_* 环境变量
  • 尊重用户配置的 OTEL_* 变量（如果已设置，不要覆盖）
  • 使用客户端凭证将遥测转发到配置的后端
对于代理作者：
  • 使用具有标准自动配置的 OpenTelemetry SDK
  • 代理操作的推荐跨度、指标和日志模式
  • 当 OTEL_* 变量存在与不存在时，遥测如何流动

​
2. 更新 docs/protocol/extensibility.mdx

添加一个指向新可观测性文档的部分，类似于可扩展性概念与其他协议功能的关系方式。简要提及遥测实践（遥测导出）在单独的文档中记录。

​
3. 更新 docs/docs.json

将 protocol/observability 添加到协议导航组。

​
常见问题

在编写本文档的过程中或随后的讨论中出现了哪些问题？

​
这与 params._meta 中的追踪传播有什么关系？

它们是互补的：
  • 追踪传播（params._meta 包含 traceparent 等）传递追踪上下文，以便跨度可以关联
  • 遥测导出（此 RFD）定义代理发送实际跨度/指标/日志数据的位置
两者都需要用于端到端可观测性。

​
如果代理不使用 OpenTelemetry 怎么办？

没有 OTEL SDK 的代理只需忽略环境变量。不会造成伤害。随着越来越多的代理采用 OpenTelemetry，生态系统会受益。

​
如果用户已经配置了 OTEL_* 环境变量怎么办？

如果环境中已经设置了 OTEL_* 变量，客户端不应覆盖它们。用户配置的遥测设置优先，允许用户在他们希望时将代理遥测导向自己的后端。

​
为什么不定义 ACP 特定的遥测消息？

这会重复 OTLP 功能，增加 ACP 的实现负担，并强制代理作者使用非标准 API。使用 OTLP 意味着代理可以使用标准工具和文档。

​
对于不是作为子进程启动的代理怎么办？

此 RFD 侧重于客户端启动代理的 stdio 传输。对于其他传输（HTTP 等），代理需要替代的配置机制，这可以在未来的 RFD 中解决。

​
您考虑了哪些替代方法，为什么选择这一个？

  1. 通过 ACP 隧道传输遥测 - 由于队头阻塞问题和实现复杂性被拒绝
  2. 代理直接导出到后端 - 因为需要与代理共享凭证被拒绝
  3. 基于文件的遥测 - 因为不支持实时显示并增加复杂性被拒绝
环境变量方法：
  • 使用现有标准（OTLP、OpenTelemetry SDK 约定）
  • 将遥测保持在 ACP 消息之外
  • 让客户端控制遥测的去向，而不暴露凭证
  • 无需更改 ACP 消息格式

​
修订历史

  • 2025-12-04：初始草稿