Skip to content

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
没有步数上限模型陷入循环,程序卡死还一直烧 tokenMAX_STEPS 强制中断并在超限时给出提示

⚠️ 踩坑:这三个坑只要踩过一遍,以后看任何 Agent 框架的源码都会觉得眼熟 —— 它们干的就是同一件事。

1.3 一次工具往返的全貌 ​

注意模型从头到尾没有执行任何代码,它只是"点了菜";真正动手的是循环里的 TOOL_MAP。这个认知很关键 —— 它意味着工具的安全边界必须由你(服务端)来守,不能指望模型自律。第三篇讲沙箱时会回到这一点。

二、工具系统与健壮性 ​

2.1 从声明到分发 ​

工具系统只有三个部件,Stage 4 把它们讲得很干净:

  1. tools 声明:告诉模型有哪些工具、每个工具要什么参数(JSON Schema)
  2. TOOL_MAP 分发表:工具名到实际函数的映射,加工具就往这里加一行
  3. 参数解析:模型传回的是 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 只增不减,一定会撞上上下文上限,所以需要截断或摘要压缩
本文阅读--次|全站访问--次|访客--人