2. Agent埋点概念与边界
2.1 什么是Agent——埋点视角的定义
在埋点语境中，Agent 不是泛指任何软件代理，而是特指基于大语言模型（LLM）的自主决策实体。与常规业务组件相比，Agent 的核心特征在于其决策路径不固定，由模型根据上下文动态生成。这使得埋点的关注点从“记录固定逻辑的执行结果”转向“追踪可变决策链的完整过程”。
- 感知 – 接收用户指令、系统事件、环境状态。
- 推理 – 规划任务拆解、选择分支、调用模型。
- 执行 – 调用外部工具（API、数据库、搜索、文件系统）。
- 记忆 – 读写会话上下文与长期知识。
埋点启示：Agent 的“不可预编程性”要求埋点方案必须覆盖推理过程而不仅仅是输入/输出，否则无法审计模型行为、定位失败根因。
2.2 Agent埋点的范围——四层数据边界
Agent 埋点并非全量采集，而是按分层边界定义数据范围。每层对应 Agent 生命周期中的一个关键阶段，共同构成 Reach 数据（覆盖范围数据）的主体；Impact 数据（影响效果数据）则通过跨层关联分析获得。
| 层次 | 数据内容 | 采集时机 | 典型埋点事件 |
|---|---|---|---|
| 输入层 | 用户指令、系统触发、上下文快照 | 消息到达 Agent 入口 | agent.input.received |
| 推理层 | 推理步骤、模型调用、分支选择 | 每次 LLM 调用或路由决策 | agent.reasoning.step |
| 执行层 | 工具调用、API 请求、返回结果 | 工具执行前后 | agent.tool.invoke |
| 记忆层 | 会话状态、长期记忆读写 | 记忆存取操作时 | agent.memory.access |
Reach 与 Impact 的分工：Reach 数据回答“Agent 覆盖了哪些会话、用户、场景”；Impact 数据回答“Agent 行为对业务结果产生了什么影响”。四层埋点先产出 Reach 数据，再通过归因模型推导 Impact。
2.3 与前端埋点的区分
前端埋点关注用户界面交互，Agent 埋点关注智能决策行为。二者在数据源、采集方式、结构上存在本质差异：
| 对比维度 | 前端埋点 | Agent 埋点 |
|---|---|---|
| 数据源 | 浏览器 / 客户端 UI 事件 | Agent 运行时上下文 |
| 采集方式 | 事件监听 + SDK 自动上报 | 代码注入 + 中间件拦截 |
| 数据结构 | 扁平化事件（event, params, timestamp） | 树形决策链（steps, calls, branches） |
| 信任链路 | 客户端 → 上报网关 → 存储 | Agent 沙箱 → 审计代理 → 存储 |
| 关键指标 | PV / UV / 点击率 / 转化率 | 决策耗时 / 工具成功率 / 分支分布 |
常见误区：不要把 Agent 的前端交互（如聊天输入框）埋点归入 Agent 埋点。那仍然是前端埋点范畴。Agent 埋点只采集推理与执行阶段的数据。
2.4 与后端日志的区分
后端日志记录服务端系统行为，Agent 埋点记录智能决策行为。虽然 Agent 通常也运行在后端，但关注维度完全不同：
| 对比维度 | 后端日志 | Agent 埋点 |
|---|---|---|
| 数据源 | 服务请求 / 响应、系统指标 | Agent 推理步骤、工具调用 |
| 采集方式 | 日志框架（log4j / logback） | 运行时拦截 + 链路追踪 |
| 数据结构 | 结构化日志（JSON 行） | 语义化决策事件（含推理链） |
| 信任链路 | 服务框架 → 日志收集器 → 存储 | Agent 沙箱 → 审计日志 → 存储 |
| 关键指标 | QPS / 错误率 / 响应时间 | 推理效率 / 工具使用率 / 记忆命中率 |
重合区域：Agent 的工具调用最终会触发后端服务请求。此时两份日志应该通过 traceId 关联，而不是互相替代。Agent 埋点关注“为什么调用”，后端日志关注“调用结果是否正常”。
2.5 边界总览——三类埋点的关系
下图以前端埋点、Agent 埋点、后端日志三个域展示各自的覆盖范围、核心节点以及数据流转边界。
2.6 选型权衡——何时启用 Agent 埋点
Agent 埋点并非全场景适用。以下条件同时满足时优先选择：
- 需要追踪决策过程而非仅结果（审计、归因、模型改进）。
- 涉及多步骤工具调用，需要跨步关联分析。
- 需要评估模型推理质量（分支合理性、幻觉频率）。
- 存在持久化记忆，需要审计记忆读写行为。
若仅需记录“用户→Agent→结果”的三元组，使用后端日志+自定义字段即可，不必引入完整 Agent 埋点方案。
2.7 落地风险点
| 风险 | 影响 | 应对策略 |
|---|---|---|
| 埋点侵入影响推理性能 | 用户体验下降 | 异步采集 + 采样率控制（按场景动态调整） |
| 决策链数据量爆炸 | 存储成本过高 | 结构化压缩 + 按生命周期分级存储 |
| 敏感信息泄露（用户指令/上下文） | 合规风险 | 脱敏过滤 + 字段级访问权限控制 |
| 数据可信度争议 | 分析结论偏差 | 信任链路签名 + 定时一致性审计 |
2.8 落地步骤概览
- 定义数据模型 – 事件类型枚举、字段规范、层级关系。
- 确定采集点 – 在 Agent 框架的输入/推理/执行/记忆四层插入拦截接口。
- 实现运行时中间件 – 代码注入或 AOP（如 Python decorator / Go middleware）。
- 建立信任链路 – 对每条埋点事件生成签名，防止篡改。
- 配置存储与采样 – 按场景设定全量/采样比例，区分热数据与归档数据。
- 开发数据校验 – 自动化校验决策链完整性、字段格式、脱敏覆盖率。
// 埋点事件结构示例（简化）
{
"event_id": "evt_a1b2c3d4",
"agent_id": "agent-wholesale-v7",
"trace_id": "trace_xyz_001",
"layer": "execution",
"event_type": "agent.tool.invoke",
"timestamp": 1712712345678,
"data": {
"tool_name": "query_inventory",
"input": "商品SKU=88011",
"output": "available_qty=342",
"duration_ms": 1205