Learn Claude Code
s01

Agent Loop

工具与执行

Bash is All You Need

95 LOC1 个工具Single-tool agent loop
机制概览

Claude Code 内部是一个不断重复的循环。每跑一轮就跟模型对话一次：把当前的对话内容发过去，模型回一句话或者发起一次工具调用，工具的结果再回到对话里，进入下一轮。什么时候停由模型自己决定，代码不判断你的任务进行到哪一步。

本节贯穿示例
研究项目
耐心资本对企业 ESG 表现的实证项目 phase 2 收尾时
在这一节里做的事

对 docs/01_实证研究设计_耐心资本_ESG.md、CLAUDE.md、06_结果输出/tables_tsv/ 下所有 csv 表头做一次术语一致性审计——确认"耐心资本""稳定型机构投资者""关系型债权""管理者短视主义""华证 ESG 评级""KZ 指数"等 14 个保护词在跨章节落地时没有被改写成"长期资本""长期机构""长期负债"这些近义表述。

看完整机制讲解

[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12

"One loop & Bash is all you need" -- 一个工具 + 一个循环 = 一个 Agent。

Harness 层: 循环 -- 模型与真实世界的第一道连接。

问题

语言模型能推理代码, 但碰不到真实世界 -- 不能读文件、跑测试、看报错。没有循环, 每次工具调用你都得手动把结果粘回去。你自己就是那个循环。

解决方案

+--------+      +-------+      +---------+
|  User  | ---> |  LLM  | ---> |  Tool   |
| prompt |      |       |      | execute |
+--------+      +---+---+      +----+----+
                    ^                |
                    |   tool_result  |
                    +----------------+
                    (loop until stop_reason != "tool_use")

一个退出条件控制整个流程。循环持续运行, 直到模型不再调用工具。

工作原理

  1. 用户 prompt 作为第一条消息。
messages.append({"role": "user", "content": query})
  1. 将消息和工具定义一起发给 LLM。
response = client.messages.create(
    model=MODEL, system=SYSTEM, messages=messages,
    tools=TOOLS, max_tokens=8000,
)
  1. 追加助手响应。检查 stop_reason -- 如果模型没有调用工具, 结束。
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason != "tool_use":
    return
  1. 执行每个工具调用, 收集结果, 作为 user 消息追加。回到第 2 步。
results = []
for block in response.content:
    if block.type == "tool_use":
        output = run_bash(block.input["command"])
        results.append({
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": output,
        })
messages.append({"role": "user", "content": results})

组装为一个完整函数:

def agent_loop(query):
    messages = [{"role": "user", "content": query}]
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM, messages=messages,
            tools=TOOLS, max_tokens=8000,
        )
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            return

        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = run_bash(block.input["command"])
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

不到 30 行, 这就是整个 Agent。后面 11 个章节都在这个循环上叠加机制 -- 循环本身始终不变。

变更内容

组件之前之后
Agent loop(无)while True + stop_reason
Tools(无)bash (单一工具)
Messages(无)累积式消息列表
Control flow(无)stop_reason != "tool_use"

试一试

cd claude-code-for-researchers
python agents/s01_agent_loop.py

试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):

  1. Read 02_变量字典/测算方法说明.md and list all 8 PC frameworks (A1/A2/A3/A4/B1/B2/C/D)
  2. Audit "耐心资本" usage in 07_论文写作/ against the 14-term protected list in CLAUDE.md §2
  3. Find every occurrence of "长期资本" or "长线资金" in 07_论文写作/ and report file:line
  4. Run stata-mcp codebook on 04_中间数据/main_panel.dta and report obs / firms / time span