一、操作场景
Agent 可观测支持采集 AI Agent 在运行过程中产生的会话、调用链、模型调用、工具调用和 Token 消耗等数据，并提供统一的检索分析与观测能力。采集的数据写入 Agent 可观测应用关联的 Trace 日志主题。
由于 AI Agent 的形态和技术栈差异较大，Agent 可观测提供了多种接入方式。这篇帮助你快速确定适用于自身场景的接入方式。
二、选择接入方式
请在下表中找到你的接入对象，即可确定接入方式并进入对应文档。
| 场景 | 接入对象 | 接入方式 |
| AI Agent | CodeBuddy、WorkBuddy、Claude Code、Codex、Cursor、MiMo Code、OpenClaw、Pi Coding Agent、Hermes Agent、OpenCode | 主机环境：接入 AI Agent（macOS/Linux/Windows 环境）容器环境：接入 AI Agent（容器环境） |
| | DeepSeek Harness | 接入 DeepSeek Harness（插件方式） |
| Agent 框架和自研应用 | AgentScope 应用（Python、Java） | 接入 AgentScope 数据 |
| | OpenAI Agents SDK 应用 | 接入 OpenAI Agents SDK 数据 |
| | Spring AI 数据 | 接入 Spring AI 数据 |
| | 其他 Agent 框架或自研应用 | 使用 Langfuse SDK 上报 Trace 数据 |
三、接入方式对比
如果你的接入对象支持多种接入方式，或需要评估接入成本，请参考下表。
| 能力或环境 | Onesuite-Pilot 采集器 | SDK 与插件 | Langfuse SDK 上报 |
| 接入操作 | 执行一条安装命令，无需修改应用代码 | 安装依赖并新增初始化代码 | 调整 Exporter 配置 |
| 支持的系统与环境 | macOS、Linux、Windows 主机；TKE 容器环境 | 取决于应用运行环境 | 取决于应用运行环境 |
| 升级影响 | 支持自动升级，无需重启应用 | 更新依赖包版本，需要重启应用 | 更新依赖包版本，需要重启应用 |
四、和 Langfuse 的关系
如果你已使用 Langfuse SDK 做 LLM/Agent 埋点，可以把 OpenTelemetry Trace 直传腾讯云 Agent 可观测，统一做检索、调用链与成本分析，不必部署 Langfuse Server，也不必把数据发到 Langfuse Cloud。具体操作请参见 使用 Langfuse SDK 上报 Trace 数据。
五、注意事项
·可组合接入。同时使用现成 AI Agent 和自研应用时，可分别通过采集器和 SDK 接入，数据汇总到同一个 Agent 可观测应用中统一查看。所有接入方式上报的 Trace 数据均遵循同一套语义规范，可在同一应用中统一检索分析。
·同一实例请勿启用多条上报路径。例如同时启用 Onesuite-Pilot 采集器和 DeepSeek Harness 插件并上报到同一日志主题，会导致同一次任务产生重复 Trace。
六、开始接入
无论采用哪种接入方式，均需先创建 Agent 可观测应用。
1. 登录 Agent 可观测，单击应用接入创建应用。
2. 获取该应用的 Trace 日志主题 ID，用于后续接入配置。
3. 参见上方表格中的接入文档完成接入。
注意：说明：
注意：各接入文档均提供 Skill 接入方式。使用支持 Skill 的 AI 工具时，可由 AI 自动创建或复用日志主题、识别运行环境并完成接入与验证，减少手动配置。
七、其他操作
·验证接入状态：按照具体接入文档检查目标数据是否已写入，并排查无数据问题。
·查看观测数据：在 Agent 可观测 页面查看 Agent、模型和工具调用的执行关系、耗时和 Token 消耗。