HALO 完全指南：用 RLM 分析 Agent 生产轨迹，自动发现系统级故障模式
概述
运行 AI Agent 的生产环境里，trace（执行轨迹）每天都在堆积。你看到某个 Agent 偶尔失败、偶尔超时、偶尔返回错误结果——但当你手动翻看几十条 JSONL 日志时，每一条看起来都不一样，根本找不到规律。
HALO（Hierarchical Agent Loop Optimizer）就是为解决这个问题而生的。它是一个基于 RLM（Recursive Language Model）的 Agent 轨迹分析工具，能自动从生产轨迹中发现系统级的故障模式，并生成可操作的修复建议。项目由 context-labs 开源，采用 MIT 许可证，GitHub 上已获得 1000+ Star。
HALO Loop：闭环优化的核心机制
HALO 的核心理念是一个四步闭环，称为 HALO Loop：
- 收集：从 Agent harness 中收集生产轨迹。HALO 使用 OpenTelemetry 兼容的 tracing 格式，支持从 Langfuse、Arize、JSONL 文件等多种来源导入。
- 分析：将轨迹喂给 HALO-RLM 引擎。引擎会将轨迹分解，理解不同执行之间的共同故障模式，生成分析报告。
- 修复：将分析报告发送给 Cursor、Claude Code、Codex 等编码 Agent，由它们生成并应用针对 harness 的修改。
- 部署：修改后的 harness 重新上线，收集新的轨迹，循环重复。
为什么不能直接用 Claude Code 分析 trace？HALO 的作者在实践中发现：通用编码 Agent 面对超长轨迹时，容易过拟合到单个或少量的异常上，看不到跨 execution 的系统性问题。RLM 的递归分解机制正是为处理这种「长文本中找模式」的场景而设计的。
安装
HALO 提供两种使用方式：CLI 工具和桌面应用。
CLI 安装（推荐）
pip install halo-engine halo --help
桌面应用
macOS 用户可以通过一键安装脚本获得桌面端：
curl -fsSL https://inference.net/halo/install.sh | sh
安装包是已签名的 DMG 文件，也可以在 GitHub Releases 页面直接下载。
CLI 使用详解
基本用法
HALO 需要一个 JSONL 格式的轨迹文件和一个分析提示词：
export OPENAI_API_KEY=sk-xxx halo path_to_your_traces.jsonl \ -p "Diagnose errors you find and suggest fixes"
HALO 使用标准的 OpenAI 环境变量 OPENAI_API_KEY 和 OPENAI_BASE_URL，可以轻松切换为任何兼容的 API 提供商。
关键参数
HALO 的 CLI 参数设计非常细致，以下是几个最常用的：
| 参数 | 默认值 | 说明 |
|---|---|---|
TRACE_PATH | 必填 | JSONL 轨迹文件路径 |
--prompt, -p | 必填 | 分析提示词 |
--model, -m | gpt-5.4-mini | 主模型（也作为合成和压缩的回退） |
--synthesis-model | 同 --model | 轨迹摘要模型（推荐用小模型如 gpt-4.1-nano） |
--compaction-model | 同 --model | 上下文压缩模型（最大 token 消耗者，强烈建议用小模型） |
--max-depth | 2 | 子 Agent 最大递归深度 |
--max-turns | 20 | 每个 Agent 的最大轮次 |
--max-parallel | 10 | 最大并行子 Agent 数 |
--telemetry | 关闭 | 开启 OpenInference 遥测追踪 |
切换 API 提供商示例
halo traces.jsonl \ -p "Find recurring failures" \ --base-url https://openrouter.ai/api/v1 \ -H "HTTP-Referer: https://example.com"
Telemetry 遥测
HALO 可以输出自身运行的 OpenInference 轨迹（不是分析你的轨迹，而是追踪 HALO 自己内部的 LLM 调用、工具调用和 Agent 活动）：
halo traces.jsonl --prompt "..." --telemetry
当 CATALYST_OTLP_TOKEN 环境变量设置时，遥测数据会上传到 inference.net 的 Catalyst 平台；未设置时会写入本地 JSONL 文件。
Python API 集成
对于需要将 HALO 嵌入到自有工作流中的场景，Python SDK 提供了六个入口点：
from engine.main import run_engine_async, stream_engine_output_async
async for item in stream_engine_output_async(messages, config, trace_path):
logger.info("step", extra={
"sequence": item.sequence,
"agent": item.agent_name
})
选择哪个入口点取决于你对可观测性的需求：
| 函数 | 返回类型 | 适用场景 | |
|---|---|---|---|
stream_engine_async | `AsyncIterator[AgentOutputItem | AgentTextDelta]` | 实时 UI，需要所有事件包括 token delta |
stream_engine_output_async | AsyncIterator[AgentOutputItem] | 按步骤记录/持久化每个完成的 step | |
run_engine_async | list[AgentOutputItem] | 只需要最终结果，不需要中间步骤 | |
| 对应的 sync 版本 | 同上 | 同步代码中调用 |
实际效果：AppWorld 基准测试
HALO 的团队在 AppWorld 基准测试上验证了效果。AppWorld 是测试 Agent 使用多应用服务（Spotify、Venmo、文件系统、通讯录等）能力的基准集。
在仅对 harness 提示词进行优化的条件下（不修改模型本身），HALO 带来的提升非常显著：
- Gemini 3 Flash：dev 准确率从 36.8% 提升到 52.6%（+15.8 点），test 从 37.5% 提升到 48.2%（+10.7 点）
- Sonnet 4.6：dev 准确率从 73.7% 提升到 89.5%（+15.8 点），test 从 62.5% 提升到 73.2%（+10.7 点）
HALO 发现的典型问题包括：幻觉工具调用、工具参数的冗余参数、拒绝循环、语义正确性问题。每个问题都对应一个可以直接编辑的提示词修复。
排错
Q: 轨迹文件格式要求？
A: JSONL 格式，每一行是一个独立的 trace 事件。支持 OpenTelemetry 兼容格式、Langfuse 导出格式、Arize 导出格式。
Q: 模型选择建议？
A: 主模型用 gpt-5.4-mini 或同等能力模型足够。合成和压缩模型强烈建议使用更小的模型如 gpt-4.1-nano——它们是最大 token 消耗者，用小模型能显著降低成本。
Q: 桌面应用有哪些功能？
A: 桌面应用提供了轨迹导入可视化、历史浏览、分析报告展示、修复推送到编码 Agent 等图形界面功能。
Q: 私有化部署？
A: HALO 完全本地运行。轨迹文件存储在本地，LLM 调用通过你自己配置的 API 密钥发送。如果你需要托管版本，可以注册 inference.net 平台。
总结
HALO 解决的是一个真实的痛点：生产环境中 AI Agent 的轨迹数据量远超人工分析能力，而通用编码 Agent 又无法跨 execution 发现系统性问题。通过 RLM 递归分解 + 闭环优化流程，HALO 将轨迹分析从「翻日志碰运气」变成了可重复、可量化的工程流程。
如果你正在运行生产级的 Agent 服务，并且发现错误模式越来越难以定位，HALO 值得一试。
相关链接：