不用任何框架，从零手写一个 AI Agent

不用任何框架，从零手写一个 AI Agent

很多人觉得AI Agent听着很玄乎，仿佛是要用一套什么“Agent框架”才能搞出来的高端玩意儿。老实说，这事儿没你想的那么复杂。拆开来看，底层的逻辑并不比你大一那年写过的“while True”循环难多少。今天咱们就动手，把整个思路捋一遍，顺便把代码也一并端出来。

什么是 Agent？跟普通 AI 有什么区别？

先看普通AI的样子：你问一句，它答一句，典型的“一问一答”模式。特别像你每次在对话框里敲进去一个“1+1等于几”，它乖乖回一个“2”。没有上下文思考，没有工具调用，没有自主决策。

Agent 就不一样了。你给它一个任务，它自己决定用哪套方案——要不要调计算器？要不要读文件？要不要执行一段Python脚本？执行完还得看一眼结果，不满意就再来一遍，直到任务完成为止。

普通AI: "1+1等于几" → "2"
Agent: "帮我算 (15*8+200)/4" → 调计算器 → 拿结果 → "等于80"

区别就在这儿：普通AI是“问你答你”，Agent是“你布置任务，它自己干活”。

Agent 的本质：一个 while 循环

如果你看过 Week 1 的聊天机器人代码，应该对下面这个结构很眼熟：

# Week 1 的聊天机器人
while True:
    user_input = input("你: ")
    reply = api.call(user_input)
    print(f"AI: {reply}")

# Week 4 的 Agent
while not done:
    response = api.call(messages, tools=[计算器, 读文件, Python沙箱...])
    if response wants to use tool:
        result = run_tool(response.tool_name, response.args)
        messages.append(result)  # 把工具结果告诉 AI
    else:
        print(response.content)  # AI 给出最终答案
        done = True

看到了吧？结构几乎一模一样，多出来的，就是那一步“判断要不要调用工具”。

所以 Agent 不是什么天外来客，它就是你在 Week 1 基础上多走了一步——AI 不再傻傻等你教它每一步怎么做，而是自己判断：这一步需要用计算器吗？好，调用一下，拿到结果，再看下一步怎么走。一切都是围绕“while + if”这个最基础的控制流展开的。

完整代码（150行核心逻辑）

代码量其实不多，核心逻辑就在一百五十行左右。下面是一份极简但能跑的例子：

import json
from openai import OpenAI

tools = [{
    "type": "function",
    "function": {
        "name": "calculator",
        "description": "计算数学表达式",
        "parameters": {
            "type": "object",
            "properties": {
                "expression": { "type": "string" }
            },
            "required": ["expression"]
        }
    }
}]

def run_agent(client, task, max_iterations=8):
    messages = [
        {"role": "system", "content": "你是一个Agent，可以用工具完成任务。"},
        {"role": "user", "content": task}
    ]

    for i in range(max_iterations):
        response = client.chat.completions.create(
            model="deepseek-chat",
            messages=messages,
            tools=tools,  # ← 关键：告诉 AI 有哪些工具
            stream=False
        )
        msg = response.choices[0].message

        if msg.tool_calls:
            # AI 决定调工具
            messages.append(msg)
            for tc in msg.tool_calls:
                args = json.loads(tc.function.arguments)
                result = eval(args["expression"])  # 执行工具
                messages.append({
                    "role": "tool",
                    "tool_call_id": tc.id,
                    "content": str(result)
                })
            continue  # 回到循环开头，让 AI 看结果

        return msg.content  # AI 直接回答了

    return "达到最大循环次数"

这段代码看似简单，但已经完整覆盖了 Agent 的核心工作流：告诉AI你有哪些工具 → AI 自己判断要不要用 → 调用并返回结果 → AI 继续判断下一步。就这样。没有黑魔法，没有复杂框架，有的就是循环加条件判断。这才是它真正的秘密。

我做了哪些工具

一个 Agent 好不好用，很大程度上看你给它绑了多少工具。下面是这次实现中已经封装好的工具集：

工具	能干什么
calculator	安全计算数学表达式
read_file	读本地文件
write_file	写入文件
list_files	列目录
python_repl	安全执行 Python（沙箱隔离）
get_current_time	查时间
search_docs	在文档中语义搜索（接入了 RAG）

你别小看这七样工具。组合起来，很多常见任务都能自动完成，从读文件到查文档，再到执行临时脚本，一个人工智能小助理该有的样子基本都有了。

多工具组合才见真章

Agent 真正厉害的地方，不是单次调用一个工具，而是一次任务里反复、多次决策。下面就是个真实场景：

用户："先看看项目目录有什么文件，读最大的那个，然后总结"
→ Agent: list_files → 发现 plan.md 最大
→ Agent: read_file("plan.md") → 获取内容
→ Agent: 输出总结（全程自己决策，没问我"要读哪个文件"）

注意中间这一步：Agent 是先自己看了文件列表，然后判断哪个文件最大、应该读，最后才去读。全程没有问过用户“要读哪个文件”。

这才是 Agent 的“聪明”所在：不是机械执行指令，而是基于当前状态做出下一步决策。你把任务交给它，它就不再追问你，也不打断你，直接干到底。当然，前提是你给了它足够好用的工具。

关键要点

1. Tool Calling 是 API 原生能力
   ——DeepSeek 和 OpenAI 都支持调用工具，不需要任何第三方框架，只需要在请求参数中传一个 tools 列表就行。别看网上吹得天花乱坠，底层就是这么直接。

2. 非流式获取 tool_calls
   ——工具调用时不能用 stream=True，否则拿不到完整的 tool_calls 信息。这是一个小坑，但很多初学者会不小心踩进去。

3. 温度设低点
   ——Agent 决策要的是确定性，不是文采。温度设到 0.1 - 0.3 最合适，太高了它会开始“有创意”地乱调工具。

4. 安全沙箱
   ——执行 Python 的工具必须隔离。现在做法是用 AST 检查 + 黑名单过滤，避免它执行危险的系统调用。这一点绝对不能省。

项目地址

完整代码已经放出来了，GitHub 地址：github.com/Speed-Fanta

所有代码在 week04/ 和 week06/ 两个文件夹里。Week06 是升级版，加了文档检索功能，建议两个都看看。

下一篇预告：Python 新手如何用 AI 辅助两个月做出 6 个项目。到时会聊聊怎么把今天这个 Agent 用在实际项目开发中。