HALO（层次化 Agent 循环优化器）

HALO（Hierarchal Agent Loop Optimizer） 是 context-labs 开发的开源工具集（Python 包 + 桌面应用 + benchmark 工具），用专门的 RLM（Reinforcement Learning Model）引擎从 Agent 执行 trace 中分析 harness 层面的系统性故障，并生成按影响力排序的改进建议。

HALO 的核心差异点：它不用通用 LLM 做分析，而是用专为超长 trace 设计的 RLM——通用 coding assistant 容易对个别失败过拟合，RLM 能识别跨多次运行的系统性行为模式。

OpenAI 在 Agent Improvement Loop Cookbook 中将其作为 harness 改进飞轮的核心分析步骤。与 Evals（评估）工具（Promptfoo 等）判断"当前 harness 哪里不行"互补——Evals 给出通过/失败，HALO 回答"为什么失败、应该改什么、改动优先级如何"。

在改进飞轮中的位置

HALO 处于 Loop Engineering（循环工程）中 harness 改进飞轮的第五步：

flowchart LR
    T[/"Traces\n执行记录"/] --> F[/"Feedback\n人工+LLM 反馈"/]
    F --> E[/"Evals\nPromptfoo 测试套件"/]
    E --> H[/"HALO\n分析+排序建议"/]
    H --> C[/"Codex\n实施变更"/]
    C --> T

每个步骤的数据都汇入 HALO 的输入上下文：

OpenAI Cookbook 的示例还把这些输入的数量显式化：5 条 SDK execution traces、5 条 human feedback、5 条 LLM feedback、5 个 generated eval definitions、5 条 Promptfoo row results、1 个 gate summary 和 1 份当前 harness config。这个比例说明 HALO 不只是读“失败样本”，而是读一组互相校准的证据：trace 证明行为，feedback 说明重要性，eval 定义把期望行为固化，gate result 给出当前版本是否满足。

HALO 自身的迭代循环

HALO 不只是一次性分析工具——它本身也描述了一套可持续迭代的 5 步循环（Collect → Feed → Analyze → Generate → Iterate）：

flowchart LR
    C["1. Collect\n收集 trace"] --> F["2. Feed\n喂入 RLM 引擎"]
    F --> A["3. Analyze\n分解故障模式"]
    A --> G["4. Generate\ncoding agent 应用改动"]
    G --> I["5. Iterate\n重新部署，收集新 trace"]
    I --> C

每轮循环完成后，新 harness 上线，新的 trace 开始积累，再喂入下一轮分析——这与 Loop Engineering（循环工程）的核心思想直接对应：harness 通过持续的执行证据反馈自我改进，而不是靠工程师事后猜测问题在哪里。

分析输出

HALO 的报告围绕一个核心区分展开——在给出建议前，先将每个故障分类为：

• 要求缺失：harness 根本没有规定这条行为
• 规则存在但未可靠执行：规则在系统 prompt 里，但执行阶段不稳定
• 实现/可观测性缺陷：工具、验证脚本或 trace 收集本身的问题

这个分类决定了修复策略的方向——缺失的规则加进 prompt/policy，执行不稳定的可能需要改工具或加校验钩子，观测性缺陷需要修 harness 基础设施。

Codex Handoff

HALO 输出一份结构化 Markdown（codex_handoff.md），包含固定章节，可直接传给 Codex 实施：

1. Executive Summary — 当前 harness 已做好的部分 + 最高价值缺口 + eval gate 是否通过
2. Top 3 changes to implement first — 最有价值的三个改动及理由
3. Ranked recommendation table — 改动、影响、置信度、实施难度、证据来源
4. Supporting diagnosis and evidence — 故障模式及分类（缺失/未执行/缺陷）
5. Detailed recommendations — 按 Behavior contract / Runtime implementation / Output contract / Observability and evals 分组
6. Insights by feedback source — 各信号来源的贡献摘要
7. Machine-readable summary — top_priorities JSON

这个 handoff 文档把诊断、证据和实施指导打包在一起，Codex 可以直接依据它提出 diff；开发者也可以在人工审查后决定是否接受。

安装与使用

pip install halo-engine

CLI 最简用法：

halo path_to_traces.jsonl -p "Diagnose errors and suggest fixes"

支持的参数包括：模型选择、递归深度、并行执行上限、遥测开关，以及通过环境变量（OPENAI_API_KEY、OPENAI_BASE_URL）兼容 OpenAI 兼容 API。

Python API（OpenAI Cookbook 给出的流式调用方式）：

from engine.main import stream_engine_async
from engine.agents.agent_config import AgentConfig as HaloAgentConfig
from engine.engine_config import EngineConfig

agent = HaloAgentConfig(name="root", model=ModelConfig(name="gpt-4o"), maximum_turns=20)
config = EngineConfig(root_agent=agent, maximum_depth=1, maximum_parallel_subagents=2)

async for event in stream_engine_async(messages, config, context_path):
    ...  # 流式接收报告

JSONL 上下文文件混合了两类 span：

• 真实运行 span：OpenTelemetry 格式，inference.observation_kind 为 LLM/TOOL/AGENT 等
• 合成 span：用相同格式封装的 human feedback、LLM feedback、eval 定义和 gate 结果，inference.observation_kind 为 HUMAN_FEEDBACK/LLM_FEEDBACK/EVAL/EVAL_RESULT/HARNESS_CONFIG

这种设计让 HALO 能把所有信号当做统一的 trace 上下文分析，无需额外适配层。

Benchmark 结果

在 AppWorld benchmark（多步 Agent 任务完成率）上，经 HALO 优化 harness 后的提升：

改进泛化到测试集（非训练集），说明 HALO 找到的是系统性 harness 缺陷，而不是对训练 trace 的过拟合。这也印证了 Harness Engineering（驾驭工程）的绑定约束论题：harness 改进带来的增益可以超过模型升级。

与其他工具的关系

HALO 假设 trace 已经收集、eval 已经运行，它自己只做分析和输出建议，不执行任何代码变更。

项目信息

• 开源：MIT 许可，github.com/context-labs/halo
• 形态：Python 包（halo-engine）+ 桌面应用 + benchmark 工具
• 语言：TypeScript 61%、Python 36%
• 社区：1000+ stars，73 forks

相关概念

• Harness Engineering（驾驭工程） — HALO 服务的改进对象：agent harness
• Evals（评估） — HALO 的上游：eval gate 结果作为诊断输入
• Promptfoo — 与 HALO 配合的 eval 运行时
• Loop Engineering（循环工程） — HALO 实现的外层改进循环
• Codex — HALO handoff 的实施方