不用框架，百行Python代码手搓AI Agent

什么才算真正的 AI Agent

市面上关于 AI Agent 的讨论往往充满玄学。但剥离掉所有包装之后，一个 Agent 的本质只有三件事：语言模型、工具、循环。普通的聊天机器人只会从训练数据中直接作答；而 Agent 是一个运行在循环里的语言模型，它能判断自己需不需要外部信息，主动调用工具，把工具返回的结果重新交还给模型，再次决策，直到给出最终答案。据 YouTube 教程作者的说法，你听说过的所有 Agent 框架，底层都是这同一个模式。

这条视频的做法是：从一个空文件夹起步，用大约一百行代码，造出一个能查 Wikipedia、能做数学计算、还能记住上下文的 Agent。全程不依赖任何 Agent 框架。

环境准备：三步搭好地基

第一步是 Python，需要 3.10 或更新版本。Windows 用户现在可以从官网下载 Python install manager 一键安装，也可以用传统的安装器，但记得勾选 "add python.exe to path"。安装完成后在终端里用 python --version 验证。

第二步是隔离环境。用 python -m venv venv 创建虚拟环境，让本项目的依赖与系统其他部分互不干扰。第三步安装三个包：openai（与模型通信）、python-dotenv（加载密钥）、requests（调用 Wikipedia）。

模型接入：一个 Key 通吃多家

教程选择了 OpenRouter 作为模型入口。它的价值在于用一把 API Key 就能调用 OpenAI、Anthropic、Google 等多家厂商的模型，且完全兼容 OpenAI 的标准接口格式——这意味着今天学到的写法换个 base URL 就能迁移到别处。作者选用的模型是 GPT-4o mini，理由是便宜、快、且工具调用能力强。

密钥管理是新手最容易踩坑的地方。作者强调：永远不要把 Key 直接写进代码，而是放进 .env 文件，用 python-dotenv 读取；如果用 Git，务必把 .env 加入 .gitignore。

动手写 Agent 之前，先写一个 hello.py 发一条消息验证通路，确认模型能正常回复，再往上叠功能——这个习惯能省掉大量排查时间。

OpenRouter 之所以能实现“一个 Key 通吃多家”，核心在于它作为模型路由中间层，向下对接各家厂商 API，向上统一暴露为 OpenAI 兼容接口。兼容 OpenAI 格式意味着请求体、响应结构、工具调用字段都按同一套约定来写，开发者只需修改 base_url 和模型名即可切换后端。而工具调用（function calling）之所以重要，是因为它是模型与外部世界交互的标准化信号：模型不再直接输出自然语言答案，而是返回一个结构化的工具调用请求，包含工具名和参数，程序据此执行真实函数。这也解释了为什么作者选模型时特别看重“工具调用能力强”——一个不善于按 Schema 输出工具请求的模型，再便宜也无法支撑 Agent。

三个核心构件：工具、Schema、循环

工具就是普通函数

Agent 的第一个工具是计算器：接收一段数学表达式文本，返回结果。作者给出了一个务实的提醒：示例里用 eval 并关闭内置函数尚可接受，但真实产品必须换成正规的数学解析器。第二个工具搜索 Wikipedia——先找到最佳匹配条目的标题，再抓取该页摘要返回文本。最后用一个字典把工具名映射到对应函数，供循环调度。

Schema 是模型理解工具的说明书

模型读不到你的 Python 代码，所以每个工具都要用 JSON Schema 描述：名称、简短说明、参数结构。作者特别指出，description 的重要性超出多数人预期，模型正是靠它来决定调用哪个工具，所以要像给新同事讲解一样写清楚。计算器接收一个字符串参数（表达式），Wikipedia 工具接收一个字符串参数（查询词）。

JSON Schema 在此处的作用并非校验数据，而是充当模型与代码之间的契约。当工具 Schema 随每次请求一起发送时，模型看到的是工具的“自述文档”，它据此在众多工具中选择一个，并生成符合参数结构的调用请求。description 之所以关键，是因为模型没有任何其他渠道了解这个函数的真实意图——函数名和参数名只是线索，一段清晰说明“这个工具做什么、何时该用、输入是什么格式”的文字才是决策依据。因此 description 应当写得具体且可操作，避免模糊形容词；参数描述也应说明格式，例如表达式需要是合法的数学运算字符串，而非自然语言句子。

循环是整个 Agent 的心脏

run_agent 接收迄今为止的对话消息列表。在循环中，把消息和工具 Schema 一起发给模型，将回复追加进对话。随后是关键的判断：模型有没有请求调用工具？如果没有，说明它已经想清楚了，直接返回答案；如果有，就逐个解析工具调用的名称和参数，执行对应的 Python 函数，再把结果以 tool 消息的形式、通过调用 ID 关联回对话。然后循环继续。

作者还加了一个 max_steps 上限作为安全网，确保"犯迷糊"的 Agent 不会无限循环下去。这是生产级实现里不该省略的防御性设计。

工具调用结果需要“通过调用 ID 关联回对话”，是因为模型可能在同一轮中并行请求多个工具，而每个请求都会携带一个唯一 ID，工具的返回消息必须带上对应 ID，模型才能把结果与请求一一配对。这是 OpenAI 兼容接口的既定格式，也是多工具场景下不串线的关键。max_steps 作为安全阀，本质上是在限制循环的迭代次数：每轮循环都意味着至少一次模型调用，若模型反复请求工具却得不到它认为有用的结果，或因 Schema 描述不清而误判，就会陷入空转。加上限并配合日志记录，能快速定位是工具返回格式不对、description 有歧义，还是模型本身能力不足。

记忆：一个不断增长的列表

聊天部分只有一个 system 消息（设定 Agent 身份，并要求它用工具处理事实和数学问题），然后进入无限循环：读取用户输入、追加进消息列表、调用 run_agent。因为所有内容都追加到同一个 messages 列表，这个列表本身就是 Agent 的记忆。没有任何向量数据库，没有任何花哨的会话存储——上下文窗口就是记忆。

实测：多步推理如何发生

作者提了一个无法仅凭记忆回答的问题：Python 哪一年发布？距今（以 2026 年为基准）多少年？可以清晰看到 Agent 先搜索 Wikipedia 拿到 Python 的发布年份，再调用计算器用 2026 减去该年份，最终给出由真实工具结果拼装而成的答案。

接着追问"那 JavaScript 呢，同样的问题"，Agent 理解了"同样的问题"指代什么，重新搜索、重新计算并作答。这一步展示的不只是工具调用，还有上下文追踪能力。

从百行 Demo 到可用 Agent

这套最小实现的价值在于可拆解：工具是普通函数，Schema 是说明书，循环负责调度，消息列表负责记忆。理解了这四件事，你就理解了所有 Agent 框架的内核，再看 LangChain 之类的封装时就不会被抽象层迷惑。

扩展路径也很直接——任何你能写成函数的能力都可以变成工具：读文件、发邮件、查数据库。作者在结尾抛出的建议很实在：今天就试着加一个自己的工具。相比一开始就上重型框架，先手写一遍循环，对调试和排障的帮助要大得多。