如何构建你的第一个 AI 智能体：一个模型、几个工具，和一个循环

「AI 智能体」听起来好像需要一个框架、一个向量数据库，外加一个周末的搭建时间。其实不然。Anthropic 自己给出的定义出人意料地简单：智能体就是一个在循环中自主使用工具的 LLM。一旦看懂了这个模式，你完全可以用不到一百行代码构建出一个有用的第一个智能体——而同样重要的是，知道什么时候你不应该这么做。

核心循环

每一个智能体，无论多么花哨，都是同样的四步循环：

1. 你给模型一个目标，以及一份它被允许调用的工具清单。
2. 模型决定是直接回答，还是调用某个工具。
3. 你的代码运行该工具，并把结果反馈给模型。
4. 重复，直到模型说它完成了。

模型自己从不触碰你的文件系统或网络。它只会请求运行某个工具；要不要、以及怎样真正去执行，由你的代码决定。所有的安全性都活在这道缝隙里。

一个具体的例子

下面是一个最小化的智能体，它能用一个计算器工具来回答问题。重要的是其结构——同样的形态可以扩展到文件编辑、网络搜索或数据库查询。

import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "calculator",
    "description": "Evaluate a basic arithmetic expression and return the result.",
    "input_schema": {
        "type": "object",
        "properties": {"expression": {"type": "string"}},
        "required": ["expression"],
    },
}]

def run_tool(name, args):
    if name == "calculator":
        # In real code, use a safe parser, not eval()
        return str(eval(args["expression"], {"__builtins__": {}}))
    return "unknown tool"

messages = [{"role": "user", "content": "What is 1894 * 37 plus 12?"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason != "tool_use":
        print(resp.content[0].text)
        break

    tool_results = []
    for block in resp.content:
        if block.type == "tool_use":
            result = run_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
    messages.append({"role": "user", "content": tool_results})

那个 while 循环就是智能体。模型看到问题，请求用 "1894 * 37 + 12" 调用 calculator，你的代码运行它，把 70090 交还回去，模型于是写出最终答案。把计算器换成一对 read_file/write_file，你就有了一个原始的编程智能体。

真正起作用的部分是工具

模型的能力上限取决于你给它的工具，而工具的设计正是大多数初次尝试的智能体翻车的地方。Anthropic 关于为智能体编写工具的指南，归结起来就是几条规则：

• 像在为一位新同事写说明那样命名和描述工具。 search_invoices(customer_id, date_range) 胜过含糊的 query(sql)——约定越清晰，错误调用就越少。
• 返回高信噪比的结果，而不是原始数据的倾倒。 如果一个工具返回 5000 行 JSON，你就把模型的上下文预算花在了噪声上。裁剪到真正有用的部分。
• 让错误具有指导性。 「File not found: did you mean config.yaml?」能让模型自行恢复；而一段干巴巴的堆栈跟踪通常做不到。

在让它运行之前先立好护栏

因为是你的代码在执行每一次工具调用，所以安全性归你负责。在任何智能体触碰真实事物之前，需要加上三道护栏：

• 给循环设上限。 加一个最大迭代次数，这样一个犯糊涂的智能体就不会永远空转下去（也不会跑出一张账单）。
• 为破坏性操作设关卡。 任何会删除、发送或付款的操作，都应当先要求确认，或先在沙盒中运行。
• 校验工具输入。 绝不要 eval() 不可信的字符串，也不要把模型输出直接传进 shell。把每一个工具参数都当作不可信的用户输入来对待——因为它实际上就是。

什么时候不该构建智能体

早点学会的最有用的一点是：很多问题根本不需要智能体。如果步骤事先就已确定——拉取数据、做摘要、把摘要发邮件——那么一个带一两次模型调用的普通脚本会更便宜、更快、也更容易调试。Anthropic 把这类叫作工作流（workflows），并建议只要路径可预测就采用它们。只有当模型确实需要根据它发现的情况来决定下一步做什么时，才去使用真正的智能体。

从上面的四步循环开始，给它一两个描述清晰的工具，给迭代设上限，再加上一个真实的任务。你从一个能跑起来的智能体里学到的，会比从任何数量的框架文档里学到的都多。