使用Python从零搭建一个AIAgent的实战指南

要说2026年什么概念最火，AI Agent绝对榜上有名。它不再是那个只会一问一答的聊天机器人，而是进化成了一个能自己规划、调用工具、最终搞定复杂任务的智能体。今天，我们就抛开所有现成的框架，只用纯Python，从零开始手搓一个能实际跑起来的Agent，把它的核心机制彻底搞明白。

Agent的核心循环：思考、行动、观察

别看Agent听起来高大上，它的本质其实就是一个不断循环的“思考-行动-观察”过程。这个循环，就是智能体所有能力的基石。

用户输入 → LLM推理 → 决定是否调用工具 → 执行工具 → 观察结果 → 继续推理 → 输出

简单来说，Agent拿到任务后，会先“思考”一下：我需要做什么？该调用哪个工具？然后“行动”，也就是执行工具调用。接着“观察”工具返回的结果，并基于这个结果进行下一轮的“思考”。如此循环，直到任务完成或达到预设的步数限制。理解了这个闭环，就等于抓住了Agent的魂。

从最小可行版本开始

理论说再多，不如一行代码。我们先来实现一个最精简的Agent核心。这个版本只关注最核心的循环逻辑，确保你能一眼看穿它的工作原理。

import json
from openai import OpenAI

client = OpenAI()  # 确保API key已配置

# 定义工具
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"}
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "执行数学计算",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string", "description": "数学表达式"}
                },
                "required": ["expression"]
            }
        }
    }
]

# 工具实现
def get_weather(city: str) -> str:
    # 实际项目中接入天气API
    return f"{city}今天晴，气温22°C"

def calculate(expression: str) -> str:
    try:
        result = eval(expression)  # 生产环境请用安全解析器
        return str(result)
    except Exception as e:
        return f"计算错误: {e}"

TOOL_MAP = {
    "get_weather": get_weather,
    "calculate": calculate,
}

def run_agent(user_input: str, max_steps: int = 5) -> str:
    messages = [{"role": "user", "content": user_input}]

    for step in range(max_steps):
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            tools=tools,
            tool_choice="auto"
        )

        msg = response.choices[0].message
        messages.append(msg)

        # 没有工具调用，直接返回结果
        if not msg.tool_calls:
            return msg.content

        # 执行工具调用
        for tool_call in msg.tool_calls:
            fn_name = tool_call.function.name
            fn_args = json.loads(tool_call.function.arguments)

            print(f"  ? 调用工具: {fn_name}({fn_args})")
            result = TOOL_MAP[fn_name](**fn_args)

            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": result
            })

    return "达到最大步数限制"

代码不长，但五脏俱全。我们定义了两个工具（查天气和做计算），然后在一个循环里，让大模型决定何时调用、调用哪个工具，并处理返回结果。这就是Agent最核心的驱动逻辑。

看看它如何工作

写好了代码，跑起来看看效果。你会发现，简单的查询它一步到位，而需要推理的任务，它也能自主规划步骤。

# 简单查询
print(run_agent("北京天气怎么样？"))
# ? 调用工具: get_weather({'city': '北京'})
# 北京今天晴，气温22°C

# 多步推理
print(run_agent("北京和上海哪个更暖和？"))
# ? 调用工具: get_weather({'city': '北京'})
# ? 调用工具: get_weather({'city': '上海'})
# 根据查询结果，上海今天25°C，北京22°C，上海更暖和

看到第二个例子了吗？Agent并没有被“比较”这个动词难住，而是自己拆解出了需要先后获取两个城市天气信息的步骤，并正确执行。这种自主规划能力，正是智能体的魅力所在。

赋予它记忆：从单轮到会话

只会处理单轮对话的Agent，能力终究有限。一个真正实用的智能体，需要记住之前说过的话、做过的事。这就轮到记忆系统登场了。我们可以用一个简单的SQLite数据库来实现。

import sqlite3

class AgentMemory:
    def __init__(self, db_path: str = "agent_memory.db"):
        self.conn = sqlite3.connect(db_path)
        self.conn.execute("""
            CREATE TABLE IF NOT EXISTS memories (
                id INTEGER PRIMARY KEY,
                key TEXT UNIQUE,
                value TEXT,
                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
            )
        """)
        self.conn.commit()

    def sa ve(self, key: str, value: str):
        self.conn.execute(
            "INSERT OR REPLACE INTO memories (key, value) VALUES (?, ?)",
            (key, value)
        )
        self.conn.commit()

    def recall(self, key: str) -> str | None:
        row = self.conn.execute(
            "SELECT value FROM memories WHERE key = ?", (key,)
        ).fetchone()
        return row[0] if row else None

    def list_all(self) -> list[dict]:
        rows = self.conn.execute(
            "SELECT key, value FROM memories ORDER BY created_at DESC LIMIT 20"
        ).fetchall()
        return [{"key": r[0], "value": r[1]} for r in rows]

实现记忆类之后，关键一步是把它也封装成一个“工具”，加入到Agent的`tools`列表里。这样一来，Agent在推理过程中，就能自主决定何时该存储一条重要信息，又何时需要从记忆库中调取历史数据。比如，你可以告诉它“记住我的名字叫小明”，然后在后续对话中问“我叫什么？”，它就能通过调用记忆工具来回答你。跨对话的记忆能力，让Agent的实用性大大提升。

几个关键的设计原则

自己动手搭建，才能深入理解那些框架帮你封装好的细节。这里有几点经验之谈，能帮你避开不少坑：

1. 工具描述要精确：大模型完全依赖你提供的`description`来判断何时调用工具。描述模糊不清，比如把“计算器”简单描述为“处理数字”，很可能导致它在不该调用的时候乱调用。
2. 限制最大步数：必须给循环加上步数上限（比如5-10步），这是防止逻辑错误导致无限循环或成本失控的安全阀。对于大多数任务，这个步数足够了。
3. 错误处理要优雅：工具执行失败时，应该返回结构化的错误信息（如“查询超时，请重试”）并让Agent继续处理，而不是直接抛出异常导致整个进程崩溃。
4. 用流式输出提升体验：对于需要长时间推理的任务，可以考虑使用流式（Streaming）响应，让用户能看到“思考”的中间过程，体验会流畅很多。

与主流框架的对比

自己造轮子和用现成框架，怎么选？这张对比表可以帮你理清思路：

说到底，最好的学习路径往往是先通过纯代码实现理解底层原理，知道每一个齿轮是如何转动的。在此基础上，当你需要快速构建复杂应用时，再借助LangChain、CrewAI这类框架来提升开发效率。这样既能保持对技术的深度理解，又不失工程上的敏捷性。