简介:模型能力早已不是唯一瓶颈。Agent 演示能跑、生产就崩,问题几乎都出在模型之外那层基础设施——Agent Harness。本文拆解它的七大组成、上下文管理与工具层的关键设计,给出可直接落地的编排循环代码、故障对照表和分阶段建设路线,并说明如何在多模型环境下做好选型与调用管理。
很多人做 Agent 的第一版只是 chatbot,第二版接了几个工具、写了一个 ReAct loop,Demo 跑得很顺。但一旦要上生产,问题就开始集中爆发:模型忘了三步之前做过什么;工具调用静默失败;上下文窗口很快被垃圾信息填满;任务链条一长,结果就开始漂。
这些症状的根因通常不在模型,而在模型外面那整套系统。做 Agent 工程,本质上是在做 harness ;而 harness 的第一块地基是模型接入层——统一 API、鉴权、调用计量与成本可见性。这一层不必自己造,可以直接用 百度智能云词元所 这类大模型 API 服务平台完成多模型统一接入与调用管理,把工程精力留给编排和上下文。
Harness 指包裹在 LLM 之外的完整软件基础设施,通常包含七层:
| 组成 | 解决的问题 |
|---|---|
| Orchestration loop(编排循环) | 多步推理、何时停止、何时重试 |
| Tools(工具系统) | Schema 定义、参数校验、执行与结果回传 |
| Memory(记忆) | 短期消息历史 + 长期文件/向量/结构化状态 |
| Context management(上下文管理) | 预算分配、压缩、检索注入 |
| State persistence(状态持久化) | 中断恢复、多轮会话续跑 |
| Error handling(错误处理) | 失败可见化、重试与降级 |
| Guardrails(安全护栏) | 权限边界、危险操作拦截、输出校验 |
Anthropic 在 Claude Code 文档里说得很直接:驱动 Claude Code 的 SDK 就是它的 agent harness。OpenAI Codex 团队也用 agent 和 harness 两个词指代模型之外的基础设施。LangChain 的 Vivek Trivedy 给过一个经典判断: If you’re not the model, you’re the harness ——凡是不属于模型权重的部分,都属于 harness。
Agent 与 harness 的关系最容易混淆:Agent 是用户感知到的行为(有目标、会用工具、会自我修正),harness 是产生这种行为的机器。Beren Millidge 在 2023 年的《Scaffolded LLMs as Natural Language Computers》里给出的类比很准确——LLM 是 CPU,harness 是操作系统、内存和总线。所以”我做了一个 Agent”,实际含义往往是”我搭了一个 harness,然后接上一个模型”。
下面这段代码覆盖了生产级 harness 最核心的四件事:上下文预算、工具错误回传、结果限长、状态落盘。
def run_task(query: str, model, tools: dict, max_steps: int = 25):messages = [{"role": "user", "content": query}]state = {"done": False, "result": None}for step in range(max_steps):# 1) 上下文超预算时压缩,而不是盲目截断if estimate_tokens(messages) > CONTEXT_BUDGET:messages = compact(messages, keep_last=6)reply = model(messages, tools=tool_schema(tools))if reply.tool_calls:messages.append(reply.as_message())for call in reply.tool_calls:try:output = truncate(tools[call.name]( **call.args), limit=8000)except Exception as e:# 2) 错误必须回到模型,绝不能静默吞掉output = f"ERROR {type(e).__name__}: {e}"messages.append({"role": "tool", "id": call.id, "content": output})continuemessages.append({"role": "assistant", "content": reply.text})if reply.text.strip().endswith("<done>"):state.update(done=True, result=reply.text)breaksave_checkpoint(state, messages) # 3) 落盘,支持中断恢复return state
三个细节决定成败: 工具失败要以结构化文本回到模型 ,让模型自己决定重试还是换路径,静默失败是”结果漂移”最常见的来源; 工具返回值必须限长 ,一次几千行的日志足以毁掉整个上下文; max_steps 与 checkpoint 缺一不可 ,前者防止无限循环烧 token,后者让长任务可恢复。
上下文不是”塞得越多越好”,而是有预算的稀缺资源。实践中的优先级通常是:
上下文膨胀同时是成本问题:输入 token 直接决定账单。压缩策略做得好,往往比换更便宜的模型省得更多。要做模型单价与性能的横向对比、评估不同模型的性价比,可以在 词元所 上查看各模型的价格与能力信息,再结合自己的上下文规模估算真实成本。
LangChain 的实践证明了这一层的价值:他们没有换模型、没有换权重,只改了包在 LLM 外面的基础设施,就在 TerminalBench 2.0 上从 30 名开外跃升到第 5 名。另有研究项目让 LLM 自己迭代优化这套基础设施,最终达到 76.4% 的通过率,超过人工设计的系统。
这给工程团队的启示很明确: 建立自己的任务集回归评测 。固定一批真实任务,每次只改 harness 的一个变量(压缩策略、工具描述、重试次数),跑分对比。没有评测的 harness 优化,只是在换一种方式猜。
第四阶段是很多团队忽略的一步。harness 做得越完整,越应该保持模型层的可替换性——不同任务对推理深度、长上下文、工具调用格式遵循度的要求差异很大,把模型选择做成配置项而非硬编码,才能针对每类任务挑到最合适的那个。在 百度智能云词元所 上完成模型发现、选型对比与统一 API 接入,可以让这层解耦的成本降到很低。
Agent 的上限由模型决定,下限由 harness 决定。生产环境里真正拉开差距的,是错误处理是否可靠、上下文是否干净、状态能否恢复、护栏是否到位。先把 harness 这层地基打牢,再谈换更强的模型——顺序反了,换什么模型都会遇到同一批问题。