AI Agent 开发入门：从原理到一个能调用工具的最小智能体

AI Agent（智能体）开发，是指构建一种能够自主感知、推理规划、调用工具并执行任务以达成目标的系统。一句话区分：传统 AI（普通聊天机器人）是「你问一句，它答一句」；AI Agent 更像一个数字员工——你给它一个高级目标（比如「分析这家公司的财报并做成 10 页 PPT」），它能自己拆步骤、查资料、跑代码、调 API，最后把成果交给你。

1. Agent 的本质：给大模型装上「手脚和大脑」

大模型（LLM）本身只会「输入文字 → 输出文字」。Agent 开发的本质，就是在 LLM 外面套一层结构，让它能和真实世界交互、并多步自主行动。这层结构通常包含四个部分：

flowchart TD
    U["用户指令
（高级目标）"] --> B["大脑 · LLM
理解意图 / 规划 / 推理"]
    B --> P["规划 Planning
拆解子任务 + 自我反思纠错"]
    B --> M["记忆 Memory
短期上下文 + 长期知识"]
    B --> T["工具 Tools
搜索 / 数据库 / 代码 / 发邮件 / API"]
    T --> E["执行并观察结果"]
    E --> B
    B --> O["交付成果"]

    style B fill:#dbe9ff,stroke:#2563eb,stroke-width:2px
    style T fill:#ffe9d5,stroke:#b71d18

• 大脑（LLM / 推理引擎）：负责理解意图、分析问题、制定计划。
• 记忆（Memory）：短期记忆（当前对话上下文）+ 长期记忆（历史经验、知识库，常配合向量数据库）。
• 工具（Tools）：让 Agent 能「动手」——网页搜索、查数据库、跑代码、发邮件等。
• 规划（Planning）：把复杂目标拆成可执行的子任务，并能自我反思、发现错误后纠正。

2. 核心机制：ReAct 循环

让 Agent「自主」起来的关键，是一个推理 → 行动 → 观察的循环（业界叫 ReAct：Reason + Act）。模型不是一次想到底，而是边想边做、根据每一步的真实结果再决定下一步：

flowchart LR
    A["推理 Reason
下一步做什么？"] --> B["行动 Act
调用某个工具"]
    B --> C["观察 Observe
拿到工具返回"]
    C --> A
    A --> D["判断已完成
→ 输出最终答案"]

    style A fill:#dbe9ff,stroke:#2563eb
    style D fill:#d6f5e3,stroke:#1f9e57

这个循环会一直转，直到模型认为目标达成、不再需要调用工具为止。第 6 节的代码就是把这个循环用几十行写出来。

3. 开发技术栈

框架能帮你省掉很多胶水代码，但初学时强烈建议先手写一遍最小 Agent——把 ReAct 循环跑通，你才真正理解框架在背后替你做了什么。

4. 开发五步法

flowchart TD
    S1["① 定义目标与角色
它是客服？代码助手？数据分析师？"] --> S2["② 选择大模型
按能力 / 成本 / 延迟权衡"]
    S2 --> S3["③ 赋予工具
编写它能调用的函数 / API"]
    S3 --> S4["④ 设计工作流
提示词 + 规划/反思循环"]
    S4 --> S5["⑤ 部署与监控
追踪推理轨迹，保证稳定与安全"]

    style S3 fill:#ffe9d5,stroke:#b71d18

1. 定义目标与角色：先想清楚它要解决什么业务，边界在哪。
2. 选择大模型：复杂推理 / 长链路用更强的模型（如 Claude Opus 4.8），高频简单任务用更快更省的（如 Haiku 4.5）。
3. 赋予工具：把它能调用的函数和 API 写好、描述清楚——工具的描述写得好不好，直接决定模型会不会、该不该调它。
4. 设计工作流：写系统提示词，设定规划与反思的循环。
5. 部署与监控：用评估平台追踪推理轨迹，盯住稳定性和安全性。

5. 工具的「描述」是隐藏的胜负手

很多人以为 Agent 的关键是模型多强，其实工具描述的质量同样关键。模型靠工具的 description 来判断「什么时候该调用它」。一个好描述应当说清楚何时调用，而不只是说它是什么：

• ❌ 弱：get_weather：获取天气。
• ✅ 强：get_weather：查询某城市当前天气。当用户询问天气、或需要根据天气做建议时调用。

把触发条件写进描述里，模型的「该调而没调 / 不该调却调了」问题会明显减少。

6. 动手：用 Claude SDK 写一个最小 Agent

下面是一个不依赖任何 Agent 框架、直接基于 Claude 官方 SDK 手写的最小智能体。它实现了完整的 ReAct 循环：模型自己决定何时调用 get_weather 工具，我们执行后把结果回填，模型再据此给出最终回答。

先装 SDK：

pip install anthropic
# 并设置环境变量 ANTHROPIC_API_KEY

核心代码（约 50 行，可直接跑）：

from anthropic import Anthropic

client = Anthropic()  # 自动读取环境变量 ANTHROPIC_API_KEY

# ① 定义工具：告诉模型有哪些「手脚」，以及「何时该用」
tools = [
    {
        "name": "get_weather",
        "description": "查询某个城市的当前天气。当用户询问天气、或需要据此给建议时调用。",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名，如：上海"}
            },
            "required": ["city"],
        },
    }
]

# ② 工具的真实实现（真实项目里这里会去调真正的天气 API）
def run_tool(name, args):
    if name == "get_weather":
        return f"{args['city']}：晴，26°C，微风"
    return "未知工具"

# ③ Agent 主循环：推理 → 行动 → 观察 → 再推理（ReAct）
messages = [{"role": "user", "content": "上海今天适合穿什么？先查下天气再建议"}]

while True:
    resp = client.messages.create(
        model="claude-opus-4-8",            # 当前最强 Opus；可换 claude-sonnet-4-6 更省
        max_tokens=2048,
        thinking={"type": "adaptive"},      # 让模型自行决定思考深度
        tools=tools,
        messages=messages,
    )

    # 把模型这一轮的完整输出（含思考块/工具调用块）原样追加回历史
    messages.append({"role": "assistant", "content": resp.content})

    # 模型不再请求工具 → 说明它要给最终答案了，结束循环
    if resp.stop_reason != "tool_use":
        for block in resp.content:
            if block.type == "text":
                print(block.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})

跑起来，模型的内部轨迹大致是：

推理：用户问穿什么，得先知道天气 → 决定调用 get_weather(city="上海")
行动：调用工具
观察：上海：晴，26°C，微风
推理：天气拿到了，可以给穿衣建议了 → 输出最终答案

这 50 行就是一个真正的 Agent。 框架（LangChain / CrewAI 等）做的事，本质上就是把这个循环、工具注册、记忆管理封装得更好用——但内核就是上面这套。想扩展成实用 Agent，只要：把 run_tool 换成真实 API、往 tools 里加更多工具、再加上记忆（向量库）和系统提示词即可。

7. 进阶：多智能体（Multi-Agent）

单个 Agent 能力有限时，可以让多个各有分工的 Agent 协作：一个做规划、一个写代码、一个审查，由一个「协调者」分发任务、汇总结果。CrewAI、AutoGen 等框架就是干这个的。它能处理更复杂的工作流，但也带来调试难度和成本上升——先把单 Agent 打磨好，再考虑上多智能体。

8. 几个踩坑提醒

• 工具描述决定一切：模型该不该调工具，主要看描述。把「何时调用」写清楚。
• 别让上下文无限膨胀：长对话会撑爆上下文窗口，要做记忆压缩 / 摘要 / 清理。
• 高风险动作要加确认：发邮件、删数据、转账这类不可逆操作，应做人工确认（human-in-the-loop），而不是让 Agent 直接执行。
• 一定要可观测：用 LangSmith 之类的工具把每一步推理、每一次工具调用都记录下来，否则出问题根本无从排查。
• 从简单做起：能用「单次调用」或「固定工作流」解决的，就别上「自主 Agent」——Agent 更贵、更慢、更难控。

一句话总结

AI Agent = 大模型（大脑）+ 工具（手脚）+ 记忆 + 规划，靠 ReAct 循环把它们串成自主行动的闭环。开发的核心，不是把模型调得多复杂，而是把目标定清楚、把工具描述写明白、把循环跑通、把高风险动作管住。先用几十行手写一个最小 Agent 跑通闭环，再按需引入框架和多智能体——这是最稳的入门路径。