Agent Harness 从零手写(一):运行循环与工具系统
这是 Agent Harness 系列的第一篇,讲整个项目的地基:运行循环和工具系统。后面的 MCP、规划、记忆,都是往这个骨架上挂零件 —— 地基看明白了,后两篇读起来会轻松很多。
一、Agent 的心脏:运行循环
1.1 核心不到 20 行
Agent 和"聊天机器人"的分界线就是这段循环。去掉打印和边界处理,它的骨架就这么点:
python
MAX_STEPS = 5 # 最多循环几步,防止模型一直调工具死循环
for step in range(MAX_STEPS):
response = client.chat.completions.create(
model=MODEL, # 脚本顶部统一配置,换模型只改这一行
messages=messages,
tools=tools,
)
msg = response.choices[0].message
if msg.tool_calls:
# 把模型这条回复回填进历史(tool_calls 也要带上,否则下一轮对不上)
messages.append({"role": "assistant", "content": msg.content,
"tool_calls": [...]})
# 执行它要调的每个工具,把结果以 role="tool" 回传
for tc in msg.tool_calls:
messages.append({"role": "tool", "tool_call_id": tc.id,
"content": TOOL_MAP[tc.function.name]()})
continue # 回到循环顶部,让模型看到工具结果
# 没有 tool_calls = 模型给出最终答案
messages.append({"role": "assistant", "content": msg.content})
break"发请求 → 看它要不要调工具 → 执行工具并回传 → 再发请求" —— 这就是运行循环(Run Loop)。整个 Agent 体系里所有复杂的东西,都是往这个骨架上挂零件。
1.2 三个必踩的坑
| 坑 | 现象 | 正确做法 |
|---|---|---|
tool_calls 没回填历史 | 下一轮请求报错,或模型反复调同一个工具 | assistant 那条消息必须连 tool_calls 一起 append |
tool_call_id 没配对 | 服务端报参数校验错误 | 工具结果必须用同一个 tc.id 作为 tool_call_id |
| 没有步数上限 | 模型陷入循环,程序卡死还一直烧 token | MAX_STEPS 强制中断并在超限时给出提示 |
⚠️ 踩坑:这三个坑只要踩过一遍,以后看任何 Agent 框架的源码都会觉得眼熟 —— 它们干的就是同一件事。
1.3 一次工具往返的全貌
注意模型从头到尾没有执行任何代码,它只是"点了菜";真正动手的是循环里的 TOOL_MAP。这个认知很关键 —— 它意味着工具的安全边界必须由你(服务端)来守,不能指望模型自律。第三篇讲沙箱时会回到这一点。
二、工具系统与健壮性
2.1 从声明到分发
工具系统只有三个部件,Stage 4 把它们讲得很干净:
tools声明:告诉模型有哪些工具、每个工具要什么参数(JSON Schema)TOOL_MAP分发表:工具名到实际函数的映射,加工具就往这里加一行- 参数解析:模型传回的是 JSON 字符串,得解析成 Python 参数再调用
这套"声明 — 分发 — 解析"的结构,就是下一篇里 MCP 要标准化的对象。先手写一遍,才知道 MCP 到底在解决什么问题。
2.2 让错误变成对话的一部分
新手最容易写错的健壮性处理是"工具报错就抛异常"。正确做法是把异常也当成工具结果回传:
python
try:
result = TOOL_MAP[name](**args)
except Exception as e:
result = f"工具执行失败:{e}" # 让模型看见错误,它自己会换个思路这样模型能读到"失败了、原因是什么",进而换个工具或换个参数重试 —— 而不是整个程序崩掉。
💡 经验:错误从"异常"变成了"上下文",这是 Agent 健壮性的核心思路。
同类的还有两个工程细节,都在项目里踩过:模型偶尔返回空内容,所以要重试;工具可能耗时很久,所以要超时。
2.3 流式与结构化输出,各解决什么
- 流式(Stage 6):解决"等得难受"。边生成边显示,体验完全不同
- 结构化输出(Stage 7):解决"程序读不懂"。让模型返回 JSON,程序才能消费 —— 这是 Agent 之间、Agent 与业务系统之间对接的前提
- 上下文管理(Stage 8):解决"记不下了"。messages 只增不减,一定会撞上上下文上限,所以需要截断或摘要压缩