做出第一个智能体 最小构成与循环

💡 与"一次 API 调用"的差别只有循环。 只向 LLM 问一次拿到答案，那只是普通的 API 利用。一旦在其上加进"执行工具、把结果回传、再让它思考"这样的反复，它就变成了智能体。多出来的实质就是这一个循环。正因如此，先把循环彻底吃透，才是捷径。

# 最小的智能体循环（伪代码）
messages = [ user("查一下上个月的平均气温并做摘要") ]

while True:
    reply = llm.think(messages, tools=[search_tool])   # STEP1 思考

    if reply.wants_tool:                              # 有工具请求?
        result = run_tool(reply.tool_name, reply.args) # STEP2 调用
        messages.append(assistant(reply))
        messages.append(tool_result(result))           # STEP3 回传
    else:
        return reply.text                             # STEP4 完成就停下

⚠️ 一定要加次数上限。 上面的伪代码为了说明用了while True，但在真代码里，必须加上"最多转 N 圈"的刹车。LLM 没完没了地不断调用工具的死循环，是现实中经常发生的事故。详见容易踩的坑。

# ① 与 ② … 交给 LLM 的工具定义
search_tool = {
    "name": "search_weather",
    "description": "传入城市和月份，返回平均气温(℃)",
    "input_schema": {
        "city":  "string",
        "month": "number",
    },
}

# ③ … 留在手边的实体。就是个函数
def run_tool(name, args):
    if name == "search_weather":
        return weather_db.lookup(args["city"], args["month"])
    return "unknown tool"

📊 说明文字是提示词的一部分。 工具的description，是 LLM 判断"何时使用"的唯一线索。写得含糊，它就不用，或在奇怪的场合乱用。诀窍是"把要返回什么、何时该用，当成向人说明那样去写"。工具设计会在下一章的 MCP 里进一步深挖。

# A. 手写循环（伪代码 / 仿 Claude 的消息风格）
messages = [ user(goal) ]

for step in range(MAX_STEPS):          # ← 用上限做刹车
    reply = client.messages.create(
        model="claude-…",
        messages=messages,
        tools=[search_tool],
    )
    log(step, reply)                       # ← 为观察务必记录

    if reply.stop_reason == "tool_use":
        out = run_tool(reply.tool_name, reply.tool_args)
        messages += [ assistant(reply), tool_result(out) ]
    else:
        break                              # 出了最终回答 → 结束

# B. 交给 SDK 的工具运行器（伪代码）
runner = ToolRunner(
    model="claude-…",
    tools=[search_tool],       # 定义
    handlers={"search_weather": run_tool},  # 实体
)
answer = runner.run(goal)      # 循环在内部转

💡 准确的方法名请查官方文档。 这里的client.messages.create和ToolRunner都是为传达感觉的伪代码。实际的参数名、返回值的形态、模型 ID 因各家 SDK 而异，且更新频繁，请务必以官方文档确认最新版。先抓概念，细节用文档补齐——这才是不走弯路的做法。按步骤讲解的入门可参考《AI 智能体的做法（入门）》。

✅ 日志不是"高级功能"，而是从一开始就必备。 智能体内部本就难以看清，没有日志，"它为什么那样动"就完全无从得知。现在用一行print也足够。把这份观察体系化的评估与可观测性，会在第 5 章正式展开。先在这里养成"看"的习惯。

📊 这三个都是"上下文设计"的问题。 死循环、返回值肥大、上下文膨胀，根子都落在"给 LLM 传什么、传多少"这一上下文设计上。这套思路被体系化为上下文工程，是智能体开发的脊梁骨。先把"别传太多、别攒太多"当作口号。

• 最小的智能体＝把 4 要素组到最小的东西。与一次 API 利用的差别只有循环。
• 循环反复进行"思考→调用工具→回传结果→再思考→完成就停下"这一圈。次数上限的刹车必不可少。
• 工具是把定义（名称·说明·参数）交给 LLM，实体函数在手边执行。LLM 只负责请求。
• 实现有手写循环（适合学习）与 SDK 的工具运行器（适合实务）两种，内部相同。
• 从一开始就用日志观察，找出死循环·返回值肥大·上下文膨胀这些经典坑。