实践｜Agent Loop，写出第一个可控的循环

文件失败了，循环还要不要继续？

用户说：“运行 main.py，只报告结果。”文件里只有一句：

print(10 / 0)

运行会失败，但 Harness 还有工作：取得错误、保存结果、让模型读到它，再把回答交给用户。程序失败和循环结束，是两个不同的时刻。

这篇把实现放到文章里走一遍。你可以先看图里每步发生的事，再展开图下的断点验证；不需要打开仓库或配置 API Key，就能观察循环怎样继续、又在哪里停下。

沿着实现走一圈

先选“报告错误”，点下一步。图中的三个设备分别表示 Harness、模型和 Python 程序；“对应实现”标出当前涉及的函数与代码位置。注意第五步：错误已经回来，模型还没有看到它。第六步保存以后，下一次调用才有这份结果。

max_calls = 4
truncated = False


def ask(messages):
    # 固定响应替代模型；保留 stop_reason 和内容块结构。
    if truncated:
        return {"stop_reason": "max_tokens", "content": []}
    if len(messages) == 1:
        call = {"type": "tool_use", "id": "call_1", "name": "run_main", "input": {}}
        return {"stop_reason": "tool_use", "content": [call]}
    text = {"type": "text", "text": "运行失败：除零错误"}
    return {"stop_reason": "end_turn", "content": [text]}


def execute(call):
    # 直接求值替代文件进程；真实触发并捕获异常。
    try:
        10 / 0
    except ZeroDivisionError as error:
        return {"tool_use_id": call["id"], "is_error": True,
                "content": f"{type(error).__name__}: {error}", "type": "tool_result"}


messages = [{"role": "user", "content": "运行 main.py，只报告结果。"}]
for number in range(1, max_calls + 1):
    response = ask(messages)
    messages.append({"role": "assistant", "content": response["content"]})
    if response["stop_reason"] == "end_turn":
        print("answered：", response["content"][0]["text"])
        break
    if response["stop_reason"] != "tool_use":
        print("model_stopped：", response["stop_reason"])
        break
    result = execute(response["content"][0])
    messages.append({"role": "user", "content": [result]})
    print("保存", result["tool_use_id"], "；记录", len(messages))
else:
    print("call_limit：", number, "次调用；结果已保存")

走完后，再试两条路径：“只允许一次调用”会在保存结果后停下；“响应被截断”会在执行工具前停下。图下短代码使用同一组输入，点行号设置断点，再点“调试”，可回放短代码真实执行的行前快照。图仍由你手动推进。

完整实践默认使用离线模型替身，真实运行 main.py；图是对实现的推演，浏览器短代码用直接求值替代文件进程。三者观察同一个问题，执行范围各自标清。

三个函数，分别接住什么？

入口 practice.py 先选择模型接口和工作目录，再把它们交给 run_loop。循环每次向 ask_claude 取得响应；只有有效的工具请求，才会交给 run_main 执行。结果回到同一份 messages，供下一次调用读取。

run_loop 管顺序和停止，ask_claude 负责一次 API 请求，run_main 负责启动程序。这样安排后，替换模型接口不需要重写循环；程序异常也能变成可保存的工具反馈。

这里有两个容易忽略的细节。第一，保存的是完整 assistant 响应，文字和工具请求都保留。第二，结果里的 tool_use_id 要对应请求的 id。Claude 的客户端工具协议要求把结果放入 role: user 的 tool_result 内容块；这表示应用回传执行结果，不是用户又输入了一句话。

停下以后，先看执行证据

在“报告错误”路径里，工具结果有 is_error=True，最后状态却是 answered。这并不矛盾：前者说程序运行失败，后者说循环拿到了正常结束的模型回答。

对“只报告结果”这个问题，如实报告除零错误就是回答。如果用户要求“修好并验证”，同一句回答就还不够。answered 本身也不能证明工具执行过：模型可能直接返回文字。要判断任务是否完成，需要看原问题，以及记录中实际执行的请求和结果。

“只允许一次调用”则停得更早：结果保留在第三条记录里，但没有第二次模型调用。调用上限控制的是还能不能继续请求模型，不是把失败变成成功。记录目前只在进程内存中，进程退出后不会自动恢复。

在自己的电脑上运行同一例子

源码在独立的公开 Python 仓库。用 Python 3.10+ 下载并运行：

git clone https://github.com/Chengyunlai/learn-agent-harness.git
cd learn-agent-harness
python3 examples/s01-agent-loop/user_code/practice.py

默认文件包含 10 / 0。终端会标明模型是离线替身，文件真实执行；最后显示 answered 和“运行失败：除零错误”。加 --max-calls 1，就会在保存结果后以 call_limit 停下，退出码为 1。

想检查边界，可运行：

python3 examples/s01-agent-loop/user_code/verify_practice.py
python3 examples/s01-agent-loop/user_code/verify_reading.py

前者验证真实成功、除零和超时进程，以及请求/结果关联和停止控制；后者验证本文短代码的三条路径与保存前后的记录变化。短代码原文件是 user_code/reading_demo.py；完整运行时仍在 core/runtime.py。阅读源码时，可以沿图里的函数名定位。

response = client.messages.create(
    model=model, system=SYSTEM, messages=messages, tools=TOOLS,
    max_tokens=1024,
)
return response.model_dump(mode="json", exclude_none=True)

python3 -m venv /tmp/agent-loop-env
/tmp/agent-loop-env/bin/pip install -r requirements.txt
/tmp/agent-loop-env/bin/python examples/s01-agent-loop/user_code/verify_sdk.py

/tmp/agent-loop-env/bin/python examples/s01-agent-loop/user_code/practice.py --live

当前工具固定运行 main.py，不接受任意命令；文件仍以本机权限执行，是教学入口而非隔离沙箱。当问题变成“查看文件、修改代码，再验证”，循环可以保留，工具就需要扩展。这是下一步设计自然出现的需求。