大模型调用不等于 Agent:Harness 才是工程核心

作者:谁偷走了我的奶酪2026.11.17 03:35浏览量:0

简介: 大模型调用不等于 Agent。本文拆解 Harness 的上下文管理、工具调用、任务规划与文件持久化四个模块,给出可运行的主循环代码、模型选型维度和常见故障排查思路,帮助你把 Agent 从 Demo 推进到稳定可用的生产状态。

agent">一、为什么”模型 + 提示词”做不出 Agent

只写一段角色提示词再交给模型,得到的是一段回答,而不是一次执行。缺少三样东西:

  1. 无状态:模型本身不保存记忆,每一轮都要由外部程序把历史重新拼进上下文。
  2. 无手脚:模型只能输出文本。读文件、查数据库、调用接口,都需要外部程序解析输出并真正执行。
  3. 无纠错闭环:工具报错或结果不合规时,需要把错误信息回传给模型,让它自行修正并重试。

补齐这三点的那一层就是 Harness,即驾驭系统。模型负责判断下一步做什么,Harness 负责把判断变成动作,并保证动作的结果能回到模型手里。Harness 的代码量通常不大,但它的质量直接限制了 Agent 能做到的上限。同一个模型搭配不同的 Harness,在相同任务上的成功率可能差距很大,具体差距取决于任务类型和实现细节。

二、Harness 的四个核心模块

1. 上下文管理

上下文窗口既是容量上限,也直接决定调用成本,因为多数模型按输入 token 计费。工程上通常组合使用四种手段:

  • 滑动窗口:保留最近 N 轮对话,丢弃更早的内容。实现简单,但会让早期的用户目标丢失。
  • 摘要压缩:把早期历史交给模型生成结构化摘要,再用摘要替换原始文本。
  • 检索注入:不把全部资料塞进提示词,而是按需检索相关片段,即常见的 RAG 方案。
  • 工具结果裁剪:接口一次返回几百行 JSON 时,只保留模型下一步需要的字段。

裁剪时有两个容易忽略的细节。第一,用户的原始目标必须固定保留,不能被滚动窗口挤掉。第二,assistant 发出的 tool_calls 与对应的 tool 结果必须成对出现,不能只留下一半,否则多数模型接口会直接报错。

2. 工具调用

工具描述就是模型与外部系统之间的接口契约,写得好坏直接决定调用准确率。有三条经验:

  • description 要写清”什么时候用”,只写”这是什么”往往不够。
  • 参数使用严格的 JSON Schema,必填项、枚举值和格式都要约束。
  • 错误必须回传,把校验失败的原因作为工具结果返回,让模型基于错误信息二次修正。

错误结果建议统一为固定结构,例如 ok、error_code、message、missing_fields、retryable 五个字段。模型看到 missing_fields: ["order_id"] 时,比只看到一句”参数错误”更容易自行修正。

  1. tools = [{
  2. "type": "function",
  3. "function": {
  4. "name": "query_order",
  5. "description": "当用户询问订单状态或物流进度时调用。仅支持 18 位纯数字订单号。",
  6. "parameters": {
  7. "type": "object",
  8. "properties": {
  9. "order_id": {"type": "string", "pattern": "^\\d{18}$"}
  10. },
  11. "required": ["order_id"]
  12. }
  13. }
  14. }]

3. 任务规划

单轮工具调用只能解决简单任务。复杂任务需要 Harness 提供规划骨架,常见的有三种:

  • ReAct:思考、行动、观察,循环推进。适合路径不确定的探索型任务。
  • Plan-and-Execute:先生成完整计划,再逐步执行。适合流程明确、步骤可以预先列出的任务。
  • 子 Agent 分解:主 Agent 负责拆解与汇总,各个子 Agent 持有独立的上下文。这样可以避免单个上下文无限膨胀。

无论采用哪种方式,都要设置三类硬性上限:最大步数、超时时间和 token 预算。缺少这些上限时,Agent 很容易在两个动作之间来回切换,直到耗尽预算。

4. 文件读写与状态持久化

把文件系统当作外部记忆,是控制上下文膨胀最有效的办法之一。中间产物写入文件,模型只需要读取文件路径和摘要,不必把全文放进提示词。

用户偏好、历史结论这类需要跨会话保留的信息,应写入记忆表或结构化存储,下次会话按 key 取回。这样做的代价是多一次读取,但每轮调用的输入长度会明显下降。

三、最小可运行的主循环

下面的代码依赖以下接口,运行前需要按自己使用的 SDK 适配:

  • model.chat(messages, tools) 返回一条 assistant 消息字典,其中可能包含 tool_calls 列表,每个元素有 id 和 function(含 name 与 arguments,其中 arguments 为 JSON 字符串)。
  • model.context_window 为上下文窗口大小,model.tokenizer 提供 encode 方法。
  • TOOL_REGISTRY 是工具名到 Python 函数的映射,由业务侧注册。
  1. import json
  2. import time
  3. SYSTEM_PROMPT = "你是一个严谨的任务执行助手。需要外部信息时调用工具;信息足够时直接给出最终答案。"
  4. TOOL_REGISTRY = {} # 例如:TOOL_REGISTRY["query_order"] = query_order
  5. def count_tokens(text, tokenizer):
  6. return len(tokenizer.encode(text))
  7. def trim_messages(messages, model, budget_ratio=0.7):
  8. """保留 system 与原始用户目标,从最新消息往前按 token 预算回填历史。"""
  9. pinned, history = messages[:2], messages[2:]
  10. limit = int(model.context_window * budget_ratio)
  11. used = sum(count_tokens(str(m.get("content") or ""), model.tokenizer) for m in pinned)
  12. kept = []
  13. for m in reversed(history):
  14. cost = count_tokens(str(m.get("content") or ""), model.tokenizer)
  15. if used + cost > limit:
  16. break
  17. kept.append(m)
  18. used += cost
  19. kept.reverse()
  20. while kept and kept[0]["role"] == "tool": # 不留下孤立的 tool 结果
  21. kept.pop(0)
  22. return pinned + kept
  23. def run_agent(query, model, tools, max_steps=12, max_repeat=3, timeout_s=120):
  24. messages = [{"role": "system", "content": SYSTEM_PROMPT},
  25. {"role": "user", "content": query}]
  26. seen = {} # 动作指纹 -> 出现次数
  27. deadline = time.monotonic() + timeout_s
  28. for _ in range(max_steps):
  29. if time.monotonic() > deadline:
  30. return "超时,任务未完成"
  31. msg = model.chat(messages, tools=tools)
  32. messages.append(msg)
  33. calls = msg.get("tool_calls") or []
  34. if not calls: # 无工具调用即视为完成
  35. return msg.get("content", "")
  36. for call in calls:
  37. name = call["function"]["name"]
  38. try:
  39. args = json.loads(call["function"]["arguments"])
  40. fingerprint = f"{name}:{json.dumps(args, sort_keys=True)}"
  41. seen[fingerprint] = seen.get(fingerprint, 0) + 1
  42. if seen[fingerprint] > max_repeat:
  43. return "检测到重复动作,已终止"
  44. result = {"ok": True, "data": TOOL_REGISTRY[name](**args)}
  45. except Exception as e: # 错误回传,交由模型修正
  46. result = {"ok": False, "error_code": type(e).__name__,
  47. "message": str(e), "retryable": True}
  48. messages.append({"role": "tool",
  49. "tool_call_id": call["id"],
  50. "content": json.dumps(result, ensure_ascii=False)})
  51. messages = trim_messages(messages, model)
  52. return "已达到最大步数,任务未完成"

这段循环就是 Harness 的骨架:推理、调用、回填、裁剪,直到模型不再请求工具。max_steps、timeout_s 和重复动作检测共同构成终止条件。trim_messages 中的 token 计数只统计了文本内容,没有计入 tool_calls 的结构开销,实际预算应留出一定余量。

四、Harness 对模型的实际要求

选模型不能只看公开榜单分数,要看它在 Agent 场景下的工程表现。下面五个维度最值得实测:

能力维度 为什么关键 建议的实测方法
工具调用准确率 参数幻觉会直接导致业务侧报错 准备 50 条以上真实请求,统计参数完全正确的比例
结构化输出稳定性 JSON 解析失败会中断整个循环 同一输入重复调用 20 次,统计解析失败次数
长上下文有效利用率 能放进去不代表能用上,中间信息容易丢失 在长文本中埋入关键事实,统计召回成功率
指令遵循与多步推理 决定复杂任务能否一次规划正确 设计 3 到 5 步的任务,统计任务完整完成率
首 token 延迟与单价 多步循环会把单次成本放大数倍 记录每个任务的平均调用次数、耗时与总费用

实测时建议记录以下字段:模型名称、任务编号、是否成功、调用次数、输入与输出 token 数、耗时和错误类型。同一套 Harness 下的对比结果,比单独的评测分数更能反映真实表现。

由于一个 Agent 任务往往包含十几次甚至几十次模型调用,单价差异会被成倍放大。选型时应同时考虑能力与单位成本,并用自己的任务链路做小规模试跑。

五、常见问题与排查方向

  • Agent 反复执行同一动作:缺少重复检测。加入动作指纹与计数,超过阈值时强制终止,并把终止原因返回给用户。
  • 工具参数总是缺字段:Schema 过松,或 description 含糊。收紧约束,并在错误信息中明确列出缺失字段。
  • 执行到一半”失忆”:裁剪策略过于粗暴。改用摘要压缩,并把关键结论单独落盘,裁剪时始终保留原始目标。
  • 成本远超预期:没有做模型分级。简单判断交给小模型,复杂推理交给大模型,同时开启上下文缓存,并统计每个环节的 token 消耗。
  • 输出格式偶发不合规:不要一味加长提示词。在 Harness 侧增加一次格式校验与自动重试,失败时把具体的校验错误回传给模型。

排查时建议先看日志中每一步的输入、输出和工具结果,再判断问题出在模型、Schema 还是裁剪策略上。

六、安全与落地注意事项

Agent 一旦能执行动作,风险就从回答错误变成操作错误。上线前至少要做到以下几点:

  • 权限最小化:工具只开放完成任务所需的权限。删除、发送、修改权限等操作应要求人工确认。
  • 文件读写加沙箱:限定可读写的目录,写入前备份原文件,避免模型生成的路径越界。
  • 外部接口设置超时与限流:防止单次调用卡死整个循环,也防止循环在短时间内打满接口配额。
  • 工具输入视为不可信数据:模型生成的参数和工具返回的内容都要校验,不能直接拼接进命令或查询语句。

七、落地建议

先把 Harness 做扎实,再考虑更换更强的模型。一个具备完整上下文管理、可靠工具调用和明确终止条件的 Harness,通常比升级一档模型带来的稳定性收益更大。这一判断取决于具体任务,建议用第四节的方法实测确认。

当需要接入多家模型做对比或成本优化时,可以借助统一 API 层降低集成复杂度,但模型选择应以自己的任务数据为准。把精力集中在 Harness 的上下文、工具、规划和文件四个模块上,是从 Demo 走向生产的最直接路径。