Agent开发系列（七）-可观测性Agent的设计

目录

[一、可观测性在 Agent 安全里的特殊挑战](#一、可观测性在 Agent 安全里的特殊挑战)

二、三层可观测性设计

[2.1 Logs：安全事件的原始记录](#2.1 Logs：安全事件的原始记录)

[2.2 Traces：跨层级的调用链路追踪](#2.2 Traces：跨层级的调用链路追踪)

[2.3 Metrics：安全态势的高层感知](#2.3 Metrics：安全态势的高层感知)

[三、Agent 安全的可观测性特殊设计](#三、Agent 安全的可观测性特殊设计)

[3.1 上下文安全监控](#3.1 上下文安全监控)

[3.2 模型层安全监控](#3.2 模型层安全监控)

[3.3 多 Agent 场景的链路追踪](#3.3 多 Agent 场景的链路追踪)

---

可观测性不是监控的升级版，是三个维度的集合：日志（Logs）、链路追踪（Traces）、指标（Metrics）。Agent 安全场景下，这三个维度各有侧重，但最终要打通才能真正"看得见"。

一、可观测性在 Agent 安全里的特殊挑战

传统微服务的可观测性已经成熟------请求进来，链路清晰，每个节点做什么是确定的。Agent 不一样：

不确定性： Agent 的输出不是 100% 可预测的，同样输入跑两次可能得到不同结果。这意味着很多传统监控方式（检查返回值是否符合预期）在 Agent 场景失效。

长链路： Agent 处理一个请求，中间可能经过：输入解析 → 上下文组装 → N 次工具调用 → 模型推理 → 输出生成。每个环节都可能触发安全护栏，链路比传统服务长得多。

上下文即状态： Agent 的"状态"不只是数据库里的数据，还包括上下文窗口里的内容。上下文被污染是看不见的，传统的状态监控发现不了这个问题。

所以 Agent 安全的可观测性设计，必须比传统服务更细、埋点更多、告警更实时。

二、三层可观测性设计

2.1 Logs：安全事件的原始记录

设计原则：每一条安全相关操作都要记录原始日志，日志是追溯的唯一依据。

日志分层：

日志类型	记录内容	存储要求	保留周期
访问日志	用户ID、请求时间、输入摘要、输入长度	高性能存储	30天
安全日志	护栏触发记录、触发规则、判定结果	高可靠存储	6个月
审计日志	所有工具调用、所有降级行为、身份信息	防篡改存储	1年
调试日志	Chain-of-thought、工具调用详情、模型输入输出摘要	开发环境全量，生产按需采样	7天

安全日志的必填字段（每条都要有）：

{
  "event_id": "uuid",           // 全局唯一，关联追溯用
  "timestamp": "ISO8601",       // 精确到毫秒
  "session_id": "string",        // 关联同一会话所有操作
  "user_id": "string",          // 谁在操作
  "agent_id": "string",         // 哪个 Agent 在处理
  "event_type": "enum",         // INPUT_RECEIVED / GUARDRAIL_TRIGGERED / TOOL_CALLED / OUTPUT_GENERATED / ...
  "layer": "enum",              // INPUT / CONTEXT / TOOL / OUTPUT / AUDIT
  "action": "string",           // 具体操作描述
  "result": "enum",            // ALLOWED / BLOCKED / FLAGGED / FALLBACK
  "triggered_rule": "string",   // 触发了哪条规则（如果有）
  "risk_level": "enum",         // P0 / P1 / P2
  "metadata": {}                // 扩展字段：输入摘要、参数、调用链ID等
}

日志采集的技术选型：

• 高性能方案： 结构化日志直接写 Kafka/ Pulsar，后端消费写入 ClickHouse/ Elasticsearch
• 防篡改方案： 审计日志写一次，读写分离，用 append-only 存储（如 AWS S3 Object Lock 或自建 WORM 存储）
• 关键要求： 日志链路不能断。任何导致日志丢失的故障，都要触发自己的告警

2.2 Traces：跨层级的调用链路追踪

设计原则：每个请求的处理链路，从输入到输出，全链路可追溯，且能还原"当时发生了什么"。

Agent 场景的 Trace 数据结构：

Trace (整个请求)
├── Span 1: Input Received
│   ├── 输入长度、输入类型
│   ├── Layer 1 判定结果（通过 / 拦截 / 标记）
│   └── 触发规则（如果有）
│
├── Span 2: Context Assembly
│   ├── 上下文来源（用户输入 / 外部数据源）
│   ├── 上下文长度
│   └── 敏感数据检测结果
│
├── Span 3: Tool Calls (N个)
│   ├── Tool Name
│   ├── 调用参数（脱敏后）
│   ├── Layer 3 判定结果
│   ├── 执行结果（成功 / 失败 / 降级）
│   └── 执行耗时
│
├── Span 4: Model Inference
│   ├── 模型名称、版本
│   ├── 输入 token 数、输出 token 数
│   ├── 推理耗时
│   └── 安全相关输出标记（如果有）
│
├── Span 5: Output Generated
│   ├── 输出长度
│   ├── Layer 4 判定结果
│   ├── 脱敏操作记录（如果有）
│   └── 最终输出摘要
│
└── Span 6: Fallback Triggered (如果有)
    ├── 降级级别
    ├── 降级原因
    └── 恢复方式

Trace 的关联能力：

• session_id 关联同一用户的所有 Trace
• parent_span_id 关联父子调用关系
• event_id 关联到 Logs 中的具体记录
• triggered_rule 能在 Trace 中直接看到触发了哪条护栏规则

技术选型建议：

• 推荐： OpenTelemetry + Jaeger / Tempo，主流方案，接入成本低
• 替代： 如果已有 SkyWalking / Zipkin 基础设施，直接接入
• 关键要求： Agent 的每个工具调用必须是独立的 Span，不能合并。中间件的链路追踪对 Agent 场景不够细，需要在应用层手动埋点

2.3 Metrics：安全态势的高层感知

设计原则：Metrics 是给"看仪表盘的人"用的，要能一眼看出系统安全态势是否正常。

三类核心指标：

A. 流量类指标（判断系统是否被攻击）

指标名称	定义	正常范围	告警阈值
req_total	请求总量	业务基线 ± 20%	超过业务基线 3 倍
req_by_user	单用户请求频率	用户历史均值 ± 50%	超过均值 10 倍
input_avg_length	平均输入长度	历史均值 ± 30%	超过均值 5 倍
context_window_utilization	上下文窗口利用率	< 80%	> 90%

B. 护栏触发类指标（判断护栏是否有效）

指标名称	定义	正常范围	告警阈值
guardrail_trigger_rate	护栏触发率（触发数 / 总请求数）	业务基线	超过基线 5 倍
guardrail_by_layer	各层护栏触发分布	符合业务特征	某层突然激增
guardrail_false_positive_rate	误拦截率（人工审核确认是误拦截的比例）	< 5%	> 15%
guardrail_blocked_vs_flagged	拦截和标记的比例	合理分布	几乎全是标记（护栏太松）或全是拦截（护栏太严）

C. 工具调用类指标（判断工具是否被滥用）

指标名称	定义	正常范围	告警阈值
tool_call_rate	工具调用频率（次 / 请求）	业务特征基线	超过基线 3 倍
tool_call_by_type	各工具调用分布	符合业务特征	某工具突然激增
tool_call_duration_p99	工具调用耗时 P99	< 5s	> 30s
tool_call_error_rate	工具调用错误率	< 1%	> 5%
dangerous_tool_call_rate	高风险工具调用频率	极低	任何非零增长

三、Agent 安全的可观测性特殊设计

3.1 上下文安全监控

这是 Agent 场景独有的，传统的可观测性基础设施不覆盖。

监控什么：

• 上下文膨胀率：单位时间内上下文增长的速度。突然激增可能是输入洪水攻击
• 上下文来源分布：上下文中有多少来自用户直接输入，多少来自外部数据源。外部数据源占比突然升高可能是间接注入
• 敏感内容出现位置：敏感信息（PII、凭证、内部路径）出现在上下文的哪个位置。如果出现在用户输入区，说明输入层检测失败

怎么监控：

在上下文组装阶段埋点，记录上下文中每个片段的来源和内容特征。不需要记录完整内容------记录特征向量（敏感词命中、长度、来源类型）就够了。

3.2 模型层安全监控

监控什么：

• 输出置信度分布：如果模型输出的置信度普遍偏低或偏高，可能存在问题
• 输出与输入的语义一致性：输入问 A，输出答 B，且语义不相关------可能是幻觉或注入
• 模型版本与行为一致性：同一模型版本的行为是否稳定，不同时间处理相同输入结果是否一致

怎么监控：

• 在模型推理 Span 中记录输入输出的 embedding（不用存储完整文本，存储向量用于相似度比对）
• 定期跑自动化测试集，检测模型行为漂移

3.3 多 Agent 场景的链路追踪

监控什么：

• Agent 间消息的流转路径：消息从 A → B → C，每个节点的输入输出是否被正确传递
• 消息清洗是否生效：A 传给 B 的消息中，是否包含不应该出现的内部指令或上下文
• 验证 Agent 的结论准确率：验证 Agent 对上游结论的校验通过率------如果通过率接近 100%，说明验证 Agent 可能太松；如果通过率极低，说明上游 Agent 可能问题多

怎么监控：

在每个 Agent 的消息入口和出口埋点，记录消息的来源、目的地、内容特征。特别注意消息中是否包含"系统指令"类的文本特征。