Harness Engineering 06. Observability

Fri, 29 May 2026 21:00:00 +0800

这一层关注的是在生产环境中如何监控、调试并确保 Agent 行为的可靠性。与以往框架将可观测性视为生命周期钩子（Lifecycle Hooks）的副产物不同，本文将可观测性与运维提升为一等公民，因为它已经催生了专门的平台、规范和工程实践生态系统。

1. 追踪与监控平台 (Tracing and Monitoring)

可观测性的基石是结构化轨迹捕获(Structured Trace Collection)，其核心在于将每一次 LLM 调用、工具执行和检索步骤记录为一棵 tree of spans。这种结构支持对智能体行为进行过滤、回放和深度分析。

论文列举了 Langfuse、Opik、Arize Phoenix 和 MLflow 等代表性平台。为了降低系统集成门槛，业界正趋向于采用统一的检测标准，而 OpenTelemetry (OTel) 逐步成为通用的事实标准。OTel 社区发布了生成式 AI 的语义规范，定义了模型名称、温度、Token 计数和延迟等标准属性。有两个开源项目落地了这套规范，分别是 OpenLLMetry 和 OpenInference。通过 OTel，智能体轨迹数据可以无缝流入传统的微服务监控后端（如 Prometheus, Jaeger, Grafana等），减少了运维负担。

此外，作者还介绍了两种更具创新性的监测范式：

基于 eBPF 的系统级监控 (AgentSight)：
- 机制：从应用程序进程外部进行监控，在 SSL 边界拦截加密流量以捕获意图，并监控内核事件（进程创建、文件 I/O、网络调用）以捕获动作。
- 核心优势：具有框架无关性，且不会被已攻破或配置错误的智能体绕过，这对安全性要求极高的部署场景至关重要。其 CPU 开销极低（小于 3%）。
结构化日志 (AgentTrace)：
- 认知表面（Cognitive）：捕捉显式的推理步骤、计划和反思。这对于调试由“推理错误”而非“系统错误”引发的故障至关重要。
- 操作表面（Operational）：记录工具调用和 API 交互。
- 上下文表面（Contextual）：记录环境状态和用户输入。

https://arxiv.org/abs/2602.10133" loading="lazy" src="https://kkbill.github.io/posts/harness-engineering-06-observability/images/image01.png"> 引用 AgentTrace: https://arxiv.org/abs/2602.10133

在看可观测性相关的内容时，以及平时与同事的交流中，发现大家对 trace 和 trajectory 这两个词常常混着用，宏观上它们应该是同义的，但不太能区分两者间细微的差异。故在此做一个记录与说明。

Trace vs. Trajectory

Trace：其核心释义是“痕迹”**。**在计算机科学中，它侧重于日志记录和程序执行流的复现。它像是一份详尽的“账单”，记录了系统在每一个微观瞬间发生了什么。

Trajectory：其核心释义是“物体移动的路径”，也就是“轨迹”。在智能体语境中，它侧重于“动作的演进过程”，展示了智能体如何从起点状态逐步移动到终点状态，强调的是宏观的连贯性和方向性。

总结，Trace 是构建 Trajectory 的基础。没有详尽的 Trace 捕捉，就无法抽象出准确的 Trajectory；而 Trajectory 是对 Trace 数据的高级叙事化表达。

Observability on kkBill's Blog

Harness Engineering 06. Observability

1. 追踪与监控平台 (Tracing and Monitoring)