简介: 大模型调用不等于 Agent。本文拆解 Harness 的上下文管理、工具调用、任务规划与文件持久化四个模块,给出可运行的主循环代码、模型选型维度和常见故障排查思路,帮助你把 Agent 从 Demo 推进到稳定可用的生产状态。
只写一段角色提示词再交给模型,得到的是一段回答,而不是一次执行。缺少三样东西:
补齐这三点的那一层就是 Harness,即驾驭系统。模型负责判断下一步做什么,Harness 负责把判断变成动作,并保证动作的结果能回到模型手里。Harness 的代码量通常不大,但它的质量直接限制了 Agent 能做到的上限。同一个模型搭配不同的 Harness,在相同任务上的成功率可能差距很大,具体差距取决于任务类型和实现细节。
上下文窗口既是容量上限,也直接决定调用成本,因为多数模型按输入 token 计费。工程上通常组合使用四种手段:
裁剪时有两个容易忽略的细节。第一,用户的原始目标必须固定保留,不能被滚动窗口挤掉。第二,assistant 发出的 tool_calls 与对应的 tool 结果必须成对出现,不能只留下一半,否则多数模型接口会直接报错。
工具描述就是模型与外部系统之间的接口契约,写得好坏直接决定调用准确率。有三条经验:
错误结果建议统一为固定结构,例如 ok、error_code、message、missing_fields、retryable 五个字段。模型看到 missing_fields: ["order_id"] 时,比只看到一句”参数错误”更容易自行修正。
tools = [{"type": "function","function": {"name": "query_order","description": "当用户询问订单状态或物流进度时调用。仅支持 18 位纯数字订单号。","parameters": {"type": "object","properties": {"order_id": {"type": "string", "pattern": "^\\d{18}$"}},"required": ["order_id"]}}}]
单轮工具调用只能解决简单任务。复杂任务需要 Harness 提供规划骨架,常见的有三种:
无论采用哪种方式,都要设置三类硬性上限:最大步数、超时时间和 token 预算。缺少这些上限时,Agent 很容易在两个动作之间来回切换,直到耗尽预算。
把文件系统当作外部记忆,是控制上下文膨胀最有效的办法之一。中间产物写入文件,模型只需要读取文件路径和摘要,不必把全文放进提示词。
用户偏好、历史结论这类需要跨会话保留的信息,应写入记忆表或结构化存储,下次会话按 key 取回。这样做的代价是多一次读取,但每轮调用的输入长度会明显下降。
下面的代码依赖以下接口,运行前需要按自己使用的 SDK 适配:
model.chat(messages, tools) 返回一条 assistant 消息字典,其中可能包含 tool_calls 列表,每个元素有 id 和 function(含 name 与 arguments,其中 arguments 为 JSON 字符串)。model.context_window 为上下文窗口大小,model.tokenizer 提供 encode 方法。TOOL_REGISTRY 是工具名到 Python 函数的映射,由业务侧注册。
import jsonimport timeSYSTEM_PROMPT = "你是一个严谨的任务执行助手。需要外部信息时调用工具;信息足够时直接给出最终答案。"TOOL_REGISTRY = {} # 例如:TOOL_REGISTRY["query_order"] = query_orderdef count_tokens(text, tokenizer):return len(tokenizer.encode(text))def trim_messages(messages, model, budget_ratio=0.7):"""保留 system 与原始用户目标,从最新消息往前按 token 预算回填历史。"""pinned, history = messages[:2], messages[2:]limit = int(model.context_window * budget_ratio)used = sum(count_tokens(str(m.get("content") or ""), model.tokenizer) for m in pinned)kept = []for m in reversed(history):cost = count_tokens(str(m.get("content") or ""), model.tokenizer)if used + cost > limit:breakkept.append(m)used += costkept.reverse()while kept and kept[0]["role"] == "tool": # 不留下孤立的 tool 结果kept.pop(0)return pinned + keptdef run_agent(query, model, tools, max_steps=12, max_repeat=3, timeout_s=120):messages = [{"role": "system", "content": SYSTEM_PROMPT},{"role": "user", "content": query}]seen = {} # 动作指纹 -> 出现次数deadline = time.monotonic() + timeout_sfor _ in range(max_steps):if time.monotonic() > deadline:return "超时,任务未完成"msg = model.chat(messages, tools=tools)messages.append(msg)calls = msg.get("tool_calls") or []if not calls: # 无工具调用即视为完成return msg.get("content", "")for call in calls:name = call["function"]["name"]try:args = json.loads(call["function"]["arguments"])fingerprint = f"{name}:{json.dumps(args, sort_keys=True)}"seen[fingerprint] = seen.get(fingerprint, 0) + 1if seen[fingerprint] > max_repeat:return "检测到重复动作,已终止"result = {"ok": True, "data": TOOL_REGISTRY[name](**args)}except Exception as e: # 错误回传,交由模型修正result = {"ok": False, "error_code": type(e).__name__,"message": str(e), "retryable": True}messages.append({"role": "tool","tool_call_id": call["id"],"content": json.dumps(result, ensure_ascii=False)})messages = trim_messages(messages, model)return "已达到最大步数,任务未完成"
这段循环就是 Harness 的骨架:推理、调用、回填、裁剪,直到模型不再请求工具。max_steps、timeout_s 和重复动作检测共同构成终止条件。trim_messages 中的 token 计数只统计了文本内容,没有计入 tool_calls 的结构开销,实际预算应留出一定余量。
选模型不能只看公开榜单分数,要看它在 Agent 场景下的工程表现。下面五个维度最值得实测:
| 能力维度 | 为什么关键 | 建议的实测方法 |
|---|---|---|
| 工具调用准确率 | 参数幻觉会直接导致业务侧报错 | 准备 50 条以上真实请求,统计参数完全正确的比例 |
| 结构化输出稳定性 | JSON 解析失败会中断整个循环 | 同一输入重复调用 20 次,统计解析失败次数 |
| 长上下文有效利用率 | 能放进去不代表能用上,中间信息容易丢失 | 在长文本中埋入关键事实,统计召回成功率 |
| 指令遵循与多步推理 | 决定复杂任务能否一次规划正确 | 设计 3 到 5 步的任务,统计任务完整完成率 |
| 首 token 延迟与单价 | 多步循环会把单次成本放大数倍 | 记录每个任务的平均调用次数、耗时与总费用 |
实测时建议记录以下字段:模型名称、任务编号、是否成功、调用次数、输入与输出 token 数、耗时和错误类型。同一套 Harness 下的对比结果,比单独的评测分数更能反映真实表现。
由于一个 Agent 任务往往包含十几次甚至几十次模型调用,单价差异会被成倍放大。选型时应同时考虑能力与单位成本,并用自己的任务链路做小规模试跑。
排查时建议先看日志中每一步的输入、输出和工具结果,再判断问题出在模型、Schema 还是裁剪策略上。
Agent 一旦能执行动作,风险就从回答错误变成操作错误。上线前至少要做到以下几点:
先把 Harness 做扎实,再考虑更换更强的模型。一个具备完整上下文管理、可靠工具调用和明确终止条件的 Harness,通常比升级一档模型带来的稳定性收益更大。这一判断取决于具体任务,建议用第四节的方法实测确认。
当需要接入多家模型做对比或成本优化时,可以借助统一 API 层降低集成复杂度,但模型选择应以自己的任务数据为准。把精力集中在 Harness 的上下文、工具、规划和文件四个模块上,是从 Demo 走向生产的最直接路径。