agent-state-bar

Agent 状态栏：通过元信息增强 Agent 轨迹管理

提示工程给的是静态指令，而 Agent 执行中还需要动态感知自身状态与任务进展。Agent 状态栏把任务进度、环境变化、工具调用计数等运行时状态整理成结构化摘要，由框架在上下文末尾持续注入。类比手机屏幕顶部始终显示时间、电量、信号——模型每次生成新回复时都能「瞥一眼」，据此做出更准确的决策。

何时使用

• Agent 反复执行相同工具调用、陷入无限循环（如超过次数限制仍在拨打）
• 模型数不清「已经调用了几次」「还剩几项 TODO」，违反显式约束
• 长任务中每次迭代的思考 token 量随上下文变长而持续增长
• Agent 过分关注局部子任务，忘记用户原始诉求和核心约束
• 小模型需要接近前沿模型的任务遵循能力
• 设计状态消息的注入方式与更新策略

核心原则

• 状态栏不是对话主体内容：它不属于用户消息、模型输出或工具结果，而是框架自动生成的状态摘要，注入在上下文最末尾，紧邻模型即将生成的新 token。
• 理论基础是「上下文学习是检索而非推理」：模型擅长查找，不擅长在一次前向传播中主动归纳统计。「已经打了几次电话」这类知识以原始记录形式分散在上下文里，模型每次决策都要花额外思考 token 扫描重算，效率极低且错误率高。
• 本质是把隐式状态提炼为显式知识：原始轨迹高度冗余，大量 token 中只含少量关键状态信息；状态栏以极低的额外 token 成本，呈现原本需要扫描数千 token 才能获得的信息。
• 显式操纵注意力分配：长上下文中早期目标和关键约束容易被后续工具结果淹没；结构化元信息放在末尾，空间上更接近新 token，获得更高注意力权重——一种「强制性的注意力引导」。
• 实测收益：提供提前算好的状态栏后，较小开源模型的准确率可以接近前沿大模型；每次迭代的思考 token 量、延迟和花费均降低约一个数量级。不带状态栏时思考量随上下文变长持续增长，带上后基本恒定。
• 状态栏是上下文压缩技术之一：它用代码确定性地维护「关于轨迹的结论」，与 LLM 驱动的压缩互补。
• 无侵入性：所有元信息以人类可读形式出现在上下文里，开发者随时可检查；不需要微调，直接在任何语言模型上起效。

实践模式

1. 注入位置：一条 user 角色的消息，放在最末尾

messages: [
  { role: "system",    content: "You are a customer service assistant..." }  ← 固定，KV Cache 已缓存
  { role: "user",      content: "Help me cancel my Xfinity plan" }
  { role: "assistant", content: null, tool_calls: [...] }   ← 第 1 轮决策
  { role: "tool",      content: "Call log..." }
  { role: "assistant", content: null, tool_calls: [...] }   ← 第 2 轮决策
  { role: "tool",      content: "Call log..." },
  { role: "user",      content: "Can you call them again to follow up?" },
  { role: "user",      content: "<agent_status>
      Current State:
      - phone_call invoked 3 times (Xfinity: 3/3 max)
      - Current time: 2025-09-14 10:30:45
      - TODO: [1] Cancel plan (in_progress)
    </agent_status>" }                                        ← 框架注入的状态栏
]

• 为什么是 user 角色而不是改 system：修改 system 消息会破坏整个前缀的缓存。这里的 user 角色只是 API 协议层面的技术选择，不等同于「来自终端用户的输入」——Harness 借用这个消息槽位，挂载框架自动生成的系统状态信息。
• 用 <agent_status> 标签包裹，便于模型识别其特殊性质。
• 因为是追加而非修改，前面所有已缓存内容都不受影响。