作者：马云雷
AgentLoop 数据飞轮实践系列 · 第 2 篇 / 共 5 篇：
上一篇：总览 —— 让 Agent 持续调优的闭环/ 下一篇：评估 —— 从黄金指标到 Rubric
数据接入是数据飞轮的起点：没有高质量的运行数据，观测、评估、实验都无从谈起。但“把数据接上来”这件事本身并不简单——Agent 不像传统微服务只有一种调用形态，它可能是开箱即用的通用 Agent，可能是基于框架研发的，可能是高代码自研的，甚至可能完全不想改一行代码。
这一篇讲清楚两件事：智能体观测与优化平台 AgentLoop 的数据接入能力是怎么设计的（为什么四种形态的 Agent 都能接），以及如何亲手把一个基于 Claude Code 的 Agent 接入平台。
技术底座：OTel 协议+探针
AgentLoop 的数据接入构建在 OTel（OpenTelemetry）标准协议之上，以探针的形式工作：
图 1：基于 OTel 标准协议的探针接入
探针会把 Agent 里各个调模型的地方、调工具的地方都以 Trace ID 的形式串联起来，并且把上下文的依赖关系完整串联，形成一张 Trace 拓扑图：
图 2：Trace 拓扑：探针以 Trace ID 串联模型调用与工具调用，还原完整执行轨迹（示意图，依据演示描述绘制）
在此基础上，再基于拓扑图组装出 Agent 完整的思考和执行轨迹。
选择 OTel + 探针不是偶然：OTel 是可观测性领域的事实标准，意味着接入不锁定、数据可互通；而探针是打磨了十多年的数据采集技术，能在不侵入业务逻辑的前提下把程序里各个角落的数据串联起来——这是整个接入能力的核心竞争力。选标准协议做底座，本质上是在保证：今天接进来的数据，未来任何基于 OTel 的生态都能消费。
四种接入方式
Agent 的形态千差万别，一套接入方式不可能通吃。针对不同形态的 Agent，AgentLoop 提供四种接入方式：
1. 通用 Agent：一键对接
针对常见的通用 Agent，AgentLoop 做了专业化的埋点，可以直接一键对接。如果你用的就是这类开箱即用的通用 Agent，不需要任何开发工作，直接采用这种方式即可。
2. Agent 框架：SDK 集成
如果 Agent 是基于 AgentScope 这类 Agent 框架研发的，直接通过集成方式就能快速完成数据的对接和上报：
图 3：基于 AgentScope 框架的 Agent 通过集成方式接入
框架集成的好处是埋点跟着框架走：框架知道模型调用、工具调用发生在哪，SDK 在这些关键位置自动完成采集，开发者几乎无感。
3. 自定义高代码：注解埋点
高代码场景（包括用 AI-coding 方式自研的 Agent）可以引用 AgentLoop 的依赖包，在程序里需要埋点的地方用注解的方式采集数据，上报到云端：
图 4：自定义高代码接入：依赖包 + 注解方式采集
这种方式把埋点位置的控制权交还给开发者：哪段逻辑需要观测，就在哪里加注解。值得一提的是，现在采用 AI-coding 方式开发的话，加几行埋点代码的成本非常低，高代码接入实际上也很简单。
4. eBPF：无侵入
如果完全不想改代码，可以用 eBPF 方案——通过内核级的监控，无需修改任何代码即可对接。它能够观测到 Agent 与模型网关之间的交互、执行工具过程中的指令，同时覆盖模型调用和 Agent 执行的观测：
图 5：eBPF 无侵入接入：内核级监控
eBPF 工作在内核层，采集对应用完全透明——适合存量系统、无法改动的闭源组件，或者就是想先看看数据再决定怎么埋点的场景。
小结：探针方式覆盖通用 Agent、Agent 框架、自定义高代码三类场景；eBPF 作为无侵入兜底。四种方式不是互斥的选择题，而是按你的 Agent 形态和改造意愿选择成本最低的一条路。
两个关键概念：Service Name 与 License Key
接入时有两个必填概念。所有数据都在同一个 AgentSpace（workspace）之下，那么怎么区分数据从哪个应用来、是谁上报的？答案就是这两个字段：
图 6：Service Name 区分应用，License Key 用于鉴权
- Service Name：同一个 AgentSpace 下，用 Service Name 区分不同的应用、区分来源是哪一种 Agent。可以为不同的 Agent 取不同的名字。它是数据的“归属标识”——后续观测、评估按 Service Name 圈定范围；
- License Key：用于数据鉴权——上报数据时需要 License Key 做身份标识和鉴权。它是数据的“通行证”，没有它数据报不上来。
实操：接入 Claude Code 构建的客服 Agent
概念讲完，动手。演示用的客服 Agent 是 AgentLoop 自身的一个 Agent，基于 Claude Code / Claude Agent SDK 构建。这种 Agent 有两种接入方式：
1. 探针方式接入；
2. Claude Code webhook 方式——从 Claude Code 支持的 webhook 把数据发出来。
本次演示采用更原生的 webhook 方案，配合 LoongSuite Pilot 完成接入。
步骤 1：获取 License Key，执行安装命令
先在控制台获取 License Key，然后执行安装命令：
图 7：在机器上执行安装命令，部署 LoongSuite Pilot
安装命令会在机器上先装一个依赖，再部署采集组件。整个过程只需要这一条命令。
步骤 2：理解采集工作机制
整个采集机制是：安装一个 LoongSuite Pilot——它是一个旁路进程；Claude Code 的配置里加了一些 webhook，会把相关信息发送到 Pilot 进程，再由 Pilot 上报到云端：
图 8：采集链路：Claude Code 经 webhook 发送到 LoongSuite Pilot 旁路进程，再上报云端（示意图）
“旁路”是这个设计的关键词：Pilot 不在 Agent 的执行路径上，采集的开销和故障都不会影响 Agent 本身——数据发不出去时，Agent 照常工作。
步骤 3：拷贝配置并重启 Agent
安装完成后，hooks 已经配置在 settings.json 里：
图 9：settings.json 里已安装好 hooks
注意： 这是 Claude Code 默认的配置文件，安装时会默认装到默认目录。我们需要把它拷贝到自己 Agent 的安装目录下面，然后重启 Agent，让 hooks 生效。这一步容易踩坑——忘了拷贝或忘了重启，数据就不会上报。
步骤 4：测试并到观测页验证
重启后做一次测试，Agent 正常响应。接着到观测页面确认数据是否上报：
图 10：观测页已能看到上报的数据
数据已经上报上来了。点开链路明细，可以看到完整的执行链路，包括大模型的处理步骤：
图 11：链路明细中可见大模型处理步骤
能看到大模型处理这一步，说明探针把模型调用也串进来了——不只是工具调用。至此，数据接入流程全部完成：从执行一条安装命令，到观测页看到完整链路，前后不到十分钟。接入打通之后，飞轮就有了持续的数据供给，下一篇进入“Agent 跑得怎么样”。
小结
| 要点 | 说明 |
| 协议底座 | OTel 标准协议 + 探针，Trace ID 串联全链路 |
| 四种方式 | 通用 Agent 一键对接 / Agent 框架集成 / 高代码注解 / eBPF 无侵入 |
| 两个概念 | Service Name（区分应用）、License Key（鉴权） |
| Claude Code 实操 | webhook + LoongSuite Pilot 旁路进程，拷贝 settings、重启生效 |
| 验证方式 | 观测页查看上报数据与链路明细 |
下一篇预告： 数据进来之后，下一步是回答“Agent 跑得怎么样”。我们将定义客服场景的黄金指标，让 AI 帮忙拆解成 Rubric，创建评估器并跑通第一个评估任务。
