AI Agent 入门指南(五):从零搭建你的第一个 Agent

从使用者到创造者——用不到 50 行代码写一个能干活的小 Agent

引子：会使用者 vs 会搭建者

前面四篇我们一直在"使用"Agent。这一篇我们要做一件不一样的事——自己写一个。

你可能觉得搭建 Agent 是件很复杂的事，需要理解深度学习、模型训练、复杂的框架……其实不是。2026 年的今天，用不到 50 行 Python 代码，就能写一个能调用工具的 Agent。

它不会像 Claude Code 那样强大，但它的核心闭环（理解目标→调用工具→根据结果推进任务）和那些"大 Agent"是一致的。读懂这不到 50 行代码，你就读懂了 Agent 的核心本质。

先说结论：用 OpenAI SDK 上手最快

搭建 Agent 的工具有很多，但对于"从零到第一个可用版本"，OpenAI SDK 是最直接的选择：

▲ 常见 Agent 搭建框架对比

这篇教程用 OpenAI Python SDK + function calling，因为：

最少的代码量——不到 50 行就能跑起来
最直观的理解——你写的每一行代码都对应 Agent 的一个核心概念
最易于迭代——加一个工具就是加一个函数的事

如果你更习惯用 Claude（Anthropic SDK），概念完全一样，只是 API 调用方式略有不同。

你的 Agent 架构

▲ Agent 架构：LLM 作为大脑，工具作为手脚

整个系统的核心循环只有四步：

接收用户指令
LLM 决定：直接回答，还是调用工具
如果要调用工具→执行工具→把结果送回给 LLM
LLM 根据工具结果生成最终回复

这个循环会一直持续，直到 LLM 判断任务完成。

完整代码：一个能查天气和设提醒的 Agent

以下是一个完整的 Agent 实现。它不到 50 行代码，但已经具备 Agent 的核心特征：理解目标、调用工具、根据结果推进任务。

import jsonfrom openai import OpenAIclient = OpenAI()  #确保已设置OPENAI_API_KEY#第一步：定义工具（带结构化返回）def get_weather(city: str) -> dict:    """查天气（模拟）"""    data = {        "北京": "晴, 22度",         "上海": "多云, 25度",        "深圳": "阵雨, 28度",         "杭州": "阴, 23度"    }    if city in data:        return {"status": "ok", "data": data[city]}    return {"status": "error", "error_message": f"没有{city}的天气数据"}def set_reminder(time: str, thing: str) -> dict:    """设提醒"""    if not time or not thing:        return {"status": "error", "error_message": "时间和事项不能为空"}    return {"status": "ok", "data": f"已设置提醒：{time}提醒你{thing}"}#工具声明（省略，同上版）tools = [    {        "type": "function",        "function": {            "name": "get_weather",            "description": "查某个城市的天气",            "parameters": {                "type": "object",                "properties": {                    "city": {"type": "string", "description": "城市名"}                },                "required": ["city"]            }        }    },    {        "type": "function",        "function": {            "name": "set_reminder",            "description": "设置提醒事项",            "parameters": {                "type": "object",                "properties": {                    "time": {"type": "string"},                    "thing": {"type": "string"}                },                "required": ["time", "thing"]            }        }    }]available_functions = {    "get_weather": get_weather,    "set_reminder": set_reminder,}#第二步：Agent运行循环messages = [    {        "role": "user",        "content": "北京明天天气怎么样？顺便帮我设个明天早上8点的闹钟提醒我带伞"    }]try:    response = client.chat.completions.create(        model="gpt-4o",        messages=messages,        tools=tools    )    while response.choices[0].message.tool_calls:        msg = response.choices[0].message        messages.append(msg)        for tc in msg.tool_calls:            #参数校验：确认工具名是否在可用列表中            if tc.function.name not in available_functions:                continue            func = available_functions[tc.function.name]            try:                args = json.loads(tc.function.arguments)                result = func(**args)            except json.JSONDecodeError:                result = {"status": "error", "error_message": "参数解析失败"}            messages.append({                "role": "tool",                "tool_call_id": tc.id,                "content": json.dumps(result, ensure_ascii=False)            })        response = client.chat.completions.create(            model="gpt-4o",            messages=messages,            tools=tools        )    print(response.choices[0].message.content)except Exception as e:    print(f"Agent运行出错: {e}")

逐行拆解：Agent 的核心机制

工具定义 = Agent 的"能力清单"

tools 数组定义了 Agent 能用什么工具。每个工具包含三样东西：

name：工具名字，LLM 通过名字来调用

description：工具描述，LLM 根据这个判断什么时候该用这个工具

parameters：参数描述，告诉 LLM 调用时需要传什么参数

这就是 "工具调用"（function calling）的核心。不是 Agent 自己"发现"工具，而是你告诉它有哪些工具、各自能做什么、需要什么参数。

While 循环 = Agent 的"思考-行动"循环

核心就是这一个 while 循环：

把消息发给 LLM
检查 LLM 是否想调用工具
如果是 → 执行工具 → 把结果放回消息列表 → 回到步骤 1
如果不是 → LLM 的回复就是最终答案

这就是第一篇讲的"感知-思考-行动"循环的代码实现。工具调用让 LLM 不再是"光说不练"的聊天机器人——它能真正做事了。

消息列表 = Agent 的"记忆"

messages 数组记录了 Agent 的完整对话与工具调用轨迹——用户的指令、LLM 的思考与工具调用决策、工具调用的输入输出。每一轮循环都会往里面追加新内容，LLM 基于完整历史做下一步判断。

这就是 Agent 记忆的最小实现形式。当然，更复杂的 Agent 会加上向量数据库（长期记忆）和摘要压缩（避免上下文超长），但核心思想都是这一个消息列表。

怎么让它变得更强大

以上代码是一个 Agent 的最小原型。要让它变得真正可用，可以沿着以下几个方向扩展：

加更多工具搜索、文件读写、数据库查询、发送邮件——每加一个函数，Agent 就多一项能力。你的 Agent 的能力边界由你提供的工具决定。
加系统提示词在 messages 列表开头加一条 system message，设定 Agent 的角色和行为规范：`"你是一个个人助手。回答要简洁，不确定就问用户，不要编造数据。"`
加记忆持久化把 messa错误处理真实环境中工具可能失败——网络超时、API 报错、参数非法。好的 Agent 会在工具失败时自动重试或向用户澄清。
换个框架

当你的 Agent 逻辑变得复杂（多步骤、多工具、多 Agent 协作），可以考虑迁移到 LangChain 或 CrewAI。但对于学习和简单场景，原生的 function calling 已经足够。

此外，如果你使用 OpenAI，也可以关注 Responses API——它内置了 Web 搜索、文件处理等能力，可以减少你自己定义工具的工作量。

▲ 从零到可用的六个步骤

你会遇到的两个坑

坑一：模型可能选错工具或传错参数

LLM 在 function calling 时通常不会在声明的工具集合之外调用不存在的工具，但它可能选错工具——比如用户说"提醒我"，模型却调了天气查询。也可能传错参数——比如把日期格式传反了。解决方案：执行前加一层参数校验（如上面代码中的 try/except 和工具名检查），验证工具名和参数是否符合预期。

坑二：工具返回的结果可能误导模型

如果工具返回了错误数据或空结果，LLM 可能会基于这个错误信息继续推理。解决方案：让每个工具返回结构化的结果——包含 status（成功/失败）、data、error_message——让 LLM 能准确判断工具执行状态。