Agentic AI 的 Harness 与可观测性

如果把一个大语言模型（LLM）比作没有内存、没有磁盘、没有 I/O 的 CPU，那么 Harness 就是包在它外面的操作系统：负责编排循环、挂载工具、管理记忆与上下文、处理错误与恢复、执行安全护栏。可观测性则是让你能看懂这台”操作系统”运行状态的手段。今天我们聊的不是”模型好不好”，而是构建智能体已非难事，真正的挑战在于如何以可靠、可问责的方式大规模地管理智能体的执行。

传统监控为什么失灵

Harness 是模型之外的一切代码、配置与执行逻辑；如果你不是模型，你就是 Harness。一个裸 LLM 像一颗没有外设的 CPU，而 harness 给它提供了工具（设备驱动）、记忆（存储系统）和编排循环（进程调度）。LangChain 在 2026 年 3 月用同一模型、同一权重，只换了一套 harness，就在 TerminalBench 2.0 排行榜上从 30 名外跃升至第 5 名——harness 工程本身决定成败。

但问题也随之而来：传统应用性能监控（APM）是为确定性系统设计的。Datadog、Prometheus、ELK 这些工具假设了三个前提——故障是确定性的、执行是短时请求/响应式的、出了问题有明确堆栈或错误码可以追。而 agent 系统同时打破了这三个前提：

这使得新的失败模式层出不穷：

• 工具被错误调用（参数合法但语义错误）
• 上下文膨胀导致”lost in the middle”（关键信息放在长文本中间时性能下降超过 30%）
• agent 陷入重规划死循环导致成本暴涨
• 多 agent 协作时消息丢失或冲突。

更致命的是错误复利：即使每一步成功率高达 99%，10 步任务端到端成功率只有约 90.4%，20 步降到约 81.8%。下图直观地展示了这种衰减：

当可观测单元从”一次请求”变成”一条轨迹”，传统监控框架就彻底不够用了。我们需要一种能够捕捉因果链、回溯决策树、回放完整执行过程的新型可观测性。

为何要重视可观测性？

可观测性是”可靠、可问责”的前提：没有轨迹，就没有调试、评估、成本治理与审计。这不是空话，而是四个真实痛点的交汇点。

• 调试非确定性系统。当你收到一条用户投诉”第 7 轮回复出了问题”，传统日志只能告诉你模型在第 7 步输出了什么，但无法回答”为什么 turn 3 的决策偏差导致了 turn 7 的崩溃”。完整的 trace 把每一次模型调用、工具调用、上下文变化都记录为带时间戳和父子关系的 span，让任何一条失败轨迹都可以被重新回放——用同样的 prompt 和历史输入在另一个模型版本上重跑，验证修复效果。AgentOps 提供的 time-travel 调试本质上就是基于这种回放能力。
• 评估与回归。模型和 prompt 的每一次变更都需要验证是否引入了新问题。但如果只有人工抽查，你既不知道测试集是否覆盖了真实失败模式，也无法量化质量变化趋势。2026 年的行业数据表明，3% 的工程团队已将 agent 投入生产，但 eval 采用率仅 52%——团队通常先发现”需要可见性”，然后才意识到”还需要评估”。可观测性平台提供的 trace-to-eval 能力（如 Braintrust 的 trace-to-test 流水线）能把生产失败直接转化为回归测试用例，用 LLM-as-judge 自动打分并关联回 trace ID。
• 成本治理。在 agent 系统中，token 用量不是单纯的账单信号，而是行为信号。一次运行的成本如果突然飙升到均值的 10 倍以上，往往不是模型变贵了，而是 agent 陷入了重试循环、反复检索或上下文膨胀。可观测性把”每会话 token 数”和”每步骤数”作为一级指标，把成本异常当作行为异常的早期预警。
• 安全与合规问责。当 agent 在客户环境中拥有工具调用权限时，每一次”调用了什么工具、传了什么参数、拿到了什么结果”都需要可审计。安全团队需要追溯 prompt injection 是否导致工具滥用，合规团队需要验证护栏（guardrail）的命中率和拦截效果。没有轨迹留存，agent 的决策就是黑箱，审计无从谈起。

如何实现从”请求日志”到”轨迹可观测性”

实现 agent 可观测性不需要推翻现有监控体系，而是把传统可观测性的三支柱”平移”到 agent 语义下：trace 记录做什么，metric 回答健康度，event 记录具体发生了什么。

数据模型：span、trace、session 三级结构

一次完整的 agent 运行对应一条 trace。trace 内部，每一次 LLM 调用、每一次工具调用、每一个 agent 步骤都成为一个 span，span 按因果关系嵌套成树。根 span 通常是 agent.run，子 span 是 gen_ai（LLM 调用），孙子 span 是 execute_tool（工具调用）。下图展示了一条真实 agent 轨迹的结构：

每个 span 上采集的元数据由 OpenTelemetry GenAI 语义约定统一命名。关键属性包括：

# OpenTelemetry GenAI 语义约定中的核心属性（以 Python 字典示意）
{
    "gen_ai.system": "openai",                          # 供应商：openai / anthropic / azure-openai
    "gen_ai.request.model": "gpt-4o",
    "gen_ai.operation.name": "chat",                    # chat / text_completion / embeddings
    "gen_ai.usage.input_tokens": 2143,
    "gen_ai.usage.output_tokens": 287,
    "gen_ai.usage.cached_tokens": 1856,
    "gen_ai.response.finish_reasons": ["tool_use"],      # end_turn / tool_use / stop
    "gen_ai.tool.name": "execute_sql",                   # 工具调用 span 使用
    "agent.tool.success": True,                          # 工具执行结果
    "agent.task_type": "report",                        # 业务自定义属性
    "agent.step_index": 3,
}

插桩方式：自动 + 手动

OpenTelemetry 在 2025 到 2026 年间推出了 GenAI 语义约定，并在 v1.37 中纳入了 agent span 类型（invoke_agent、execute_tool、检索等）。auto-instrumentation 已覆盖 OpenAI、Anthropic、LangChain、LlamaIndex 等主流框架，你通常只需要几行初始化代码即可拿到结构化 trace，无需修改业务逻辑。性能开销实测低于 1ms/次调用，而 LLM API 延迟通常在 100ms 到 30s 之间，可忽略不计。

但对于自定义 agent loop，你需要手动插桩。以下是一个基于 OpenTelemetry Python SDK 的最小示例，展示了如何把 ReAct 循环中的每一步都变成可观测的 span：

from opentelemetry import trace

tracer = trace.get_tracer("app.agent")

def run_agent(user_input: str):
    with tracer.start_as_current_span("agent.run") as root:
        root.set_attribute("task_type", "report")
        root.set_attribute("session_id", "user_0421")
        messages = [{"role": "user", "content": user_input}]

        for step in range(10):
            with tracer.start_as_current_span("chat") as llm_span:
                llm_span.set_attribute("gen_ai.request.model", "gpt-4o")
                response = call_model(messages)       # 你的模型调用逻辑
                llm_span.set_attribute(
                    "gen_ai.usage.input_tokens", response.usage.input_tokens
                )
                llm_span.set_attribute(
                    "gen_ai.usage.output_tokens", response.usage.output_tokens
                )
                llm_span.set_attribute(
                    "gen_ai.response.finish_reasons", [response.stop_reason]
                )

            if response.stop_reason == "end_turn":
                break

            for block in response.tool_calls:
                with tracer.start_as_current_span("execute_tool") as tool:
                    tool.set_attribute("gen_ai.tool.name", block.name)
                    result = execute(block.name, block.input)
                    tool.set_attribute("agent.tool.success", True)
                messages.append({
                    "role": "tool", "content": result
                })

架构流水线

插桩一次，随处消费。OTel GenAI 语义约定在 2026 年已成为事实标准：Datadog 在 v1.37 中原生支持，Langfuse 在 /api/public/otel 开放了 OTLP 接收端点，Grafana 开始将 LLM trace 纳入 Loki。你的应用一旦按标准插桩，就可以从 Langfuse 无缝迁移到 Phoenix，或同时输出给 Datadog 和自建 Grafana，无需重写一行代码。

你应该盯什么指标、设什么告警

指标选择要聚焦 agent 特有的信号，而不是照搬 HTTP 请求监控。

现有方案详解：谁适合你的场景

2026 年的可观测性平台格局可以按两个维度划分：OTel 中立性 vs 框架绑定深度，以及开源/自托管 vs SaaS。下图是十个主流方案的横向对比，数据来自各平台 2026 年 Q1-Q2 的公开定价与功能文档。

几个值得留意的市场动态：Langfuse 在 2025 年 6 月将 LLM-as-judge、annotation queue、prompt experiments 和 Playground 全部开源（MIT 许可），并在 2026 年 1 月被 ClickHouse 收购（当前功能保持不变），进一步巩固了开源/自托管领域的领导地位。Traceloop（OpenLLMetry 背后的公司）于 2026 年 3 月被 ServiceNow 以约 6000–8000 万美元收购，标志着 OTel GenAI 插桩标准获得了大企业的认可。AWS Bedrock AgentCore Observability 也在 2025 年上线，以 OTel 兼容格式输出，可接入 CloudWatch、Langfuse、Datadog 等后端。

选型三档建议

• 起步（demo / 内部工具）：Langfuse 自托管或 Arize Phoenix 开源版。零成本即可看到完整 trace 和基础评估，代码改动最小。
• 生产（真实用户、有质量要求）：Langfuse Cloud（数据驻留 + 评估迭代）或 Braintrust（eval 门禁 + CI/CD 集成）。如果全量使用 LangChain/LangGraph，LangSmith 的节点级状态 diff 和图可视化是其他平台无法替代的，但退出成本也最高。
• 企业（已有 APM、多团队、合规）：Datadog LLM Observability 或 Grafana AI Observability，把 agent 监控并入现有可观测性体系；同时用 Phoenix 或 Langfuse 作为开发者调试层。关键是确保厂商原生支持 OTel GenAI Semantic Conventions——2026 年采购时最有价值的问题就是：你的平台是否原生收发 OTel GenAI 标准？

结论

可观测性不是 agent 的”加分项”，而是它从 demo 走向生产的”入场券”。Harness 决定了模型能做什么，而可观测性决定了你是否敢让它在生产环境自主运行。没有轨迹，你无法回答用户投诉；没有评估，你无法防止每次模型更新都变成一次赌博；没有成本信号，你无法发现 agent 在凌晨三点偷偷花了你三千美元做无意义循环。

如果你今天只带走四件事，那就是：

• 第一步，在你的 agent 循环里手动或自动插桩 OpenTelemetry，把每一次 LLM 调用和工具调用都变成 span。这一步的技术成本接近零，但认知收益最大。
• 第二步，定义 3–5 个核心业务指标（工具成功率、步骤数、每运行成本、eval 通过率），放进仪表盘和告警里。
• 第三步，建立 trace-to-eval 的闭环：让生产失败可以被人工标注、被自动评估、被回归测试捕获。
• 第四步，把告警阈值从”系统宕机”调整到”行为异常”——因为 agent 的失败往往不是宕机，而是安静地做错了。

Agentic AI 的竞争正在从”谁的模型更聪明”转向”谁的执行更可靠”。Harness 是执行的基础设施，可观测性是可靠性的底线。建好 harness 之后，第一件事不是加功能，而是开灯。

参考文献 / 扩展阅读

• OpenTelemetry GenAI Semantic Conventions, opentelemetry.io (v1.37, 2026).
• Anthropic,Building effective agents, anthropic.com/engineering, 2024-2025.
• Anthropic,Effective harnesses for long-running agents, anthropic.com/engineering, 2025.
• LangChain,The Anatomy of an Agent Harness, blog.langchain.dev, March 2026.
• ai,Agent Observability — Glossary, April 2026.
• ai,AI Observability and Agent Monitoring 2026, January 2026.
• ai,OpenTelemetry GenAI Conventions: The 2026 Default Schema for Agent Observability, July 2026.
• Langfuse, langfuse.com/docs, June 2025 (open-sourced evaluation modules under MIT).
• Arize AI,Phoenix, arize.com/phoenix, 2025-2026.
• Braintrust, braintrust.dev, 2025-2026.