零基础用Python构建你的第一个AI Agent完整指南

为什么Chatbot不够用？Agent能替你做事

聊天机器人只能“说”，而Agent能“做”。你问机器人日历上有什么安排，它只能回答“我看不到你的日历”；但Agent会自己调用工具、读取数据、把结果变成人话。差别不在模型本身，而在于Agent多了三样东西：目标、工具、循环。

一个典型的Agent循环是这样的：你问“周一有什么安排”，Agent把“回答这个问题”作为目标，选择日历工具，程序运行工具返回事件，Agent检查信息是否足够，够了就写答案，不够就再循环一次。这套模式一旦理解，你可以把它套用到几乎任何任务上——查邮件、看订单、更新表格。

最关键的安全设计是：AI模型永远不直接运行你的代码。它只是“请求”调用某个工具，真正执行的是你的程序，结果再回传给模型。你能控制它碰什么、不碰什么。

环境搭建：Python + VS Code + 虚拟环境

需要两个免费工具：Python和VS Code。从python.org下载最新版安装，Windows用户务必勾选“Add Python to path”。安装后用终端验证：python --version（Mac上用python3）。

VS Code从code.visualstudio.com安装，再装微软官方的Python扩展。然后创建项目文件夹和虚拟环境：用python -m venv .venv建一次，每次打开新终端激活它，最后用pip install openai-agents安装OpenAI Agents SDK。这一个包就提供了Agent、工具、记忆等能力。

虚拟环境（venv） 是 Python 内置的依赖隔离机制。每个项目创建独立的 .venv 文件夹，其中安装的包只对该项目可见，不会污染系统全局环境。这样不同项目即使依赖同一库的不同版本也能共存，避免冲突。创建命令 python -m venv .venv 只需执行一次；之后每次打开新终端，需先激活：Windows 用 .venv\Scripts\activate，macOS/Linux 用 source .venv/bin/activate。激活后终端提示符前会出现 (.venv) 标识，此时 pip install 安装的包才会装进该环境。若忘记激活，就会出现“包已安装但导入报错”的典型问题。

API Key：像密码一样对待它

到platform.openai.com创建密钥，它只显示一次，立刻复制。API用量和ChatGPT订阅是分开计费的，按量付费，所以动手之前先去账单设置里设一个消费上限。

密钥绝不写进代码，而是存成名为OPENAI_API_KEY的环境变量，SDK会自动读取。如果写进.env文件，记得把它加进.gitignore，防止推到GitHub泄露。密钥一旦泄露，删掉重建。

环境变量是操作系统提供给进程的键值对配置，程序运行时可以读取，但不会出现在源代码中。把 OPENAI_API_KEY 设为环境变量后，OpenAI SDK 会自动查找并使用它，无需在代码里显式传递。设置方式因系统而异：macOS/Linux 可在 ~/.zshrc 或 ~/.bashrc 中添加 export OPENAI_API_KEY="sk-..."；Windows 可通过“系统属性→环境变量”图形界面设置，或使用 setx 命令。注意 setx 设置后需打开新终端才生效。若使用 .env 文件，需配合 python-dotenv 等库加载，且务必将其加入 .gitignore。

十行代码写出第一个Agent

新建agent.py，从agents包导入Agent和Runner。一个Agent需要名字和instructions——instructions是你写的最重要的一行，要像给新助理交代工作一样，明确职责、语气、长度。含糊的指令只会得到含糊的Agent。用Runner.run_sync发送任务并等待结果。运行python agent.py，你就得到了一个能输出计划的Agent。

不过此时它还只是个“代码里的聊天机器人”。接下来两步才让它真正有用。

记忆：让Agent记住你

默认情况下每次运行都是空白开头——告诉它你的名字，再跑一次问它，它完全不记得。解决办法是session：导入SQLiteSession，用一个id和数据库文件创建会话，然后把session传给每次Runner调用。历史记录存在项目文件夹的memory.db里，下一轮会先加载它。

想重新开始？删掉文件或换一个session id即可。每个用户分配一个session id，对话就天然隔离——这正是客服机器人防止两个客户看到彼此聊天记录的方式。

SQLite 是一个轻量级、无服务器的嵌入式数据库，整个数据库就是单个文件（如 memory.db），无需安装额外服务。SQLiteSession 利用它把对话历史持久化到磁盘，每次运行 Agent 时自动读写。相比内存存储，SQLite 的优势是进程重启后记忆不丢失；相比完整数据库，它零配置、适合本地和小型应用。Session 的隔离通过 session_id 实现：相同 id 共享历史，不同 id 完全独立。生产环境中若需多用户并发，应注意 SQLite 的写入锁限制，可考虑换用 PostgreSQL 等方案，但入门阶段 SQLite 足够。

工具：一个装饰器让Agent能动手

工具就是一个加了@function_tool装饰器的Python函数。docstring至关重要——Agent靠它判断这个工具做什么、什么时候用。示例工具返回演示数据方便安全测试，之后换成真实日历，其他代码不用动。把工具放进tools列表，保留session，再包一个循环，你就能持续对话直到输入quit。

注意类型提示：day是字符串。SDK会把函数名、docstring和类型提示翻译成模型能读的描述。如果Agent忽略某个工具，通常的修法是把docstring写清楚，而不是加更多代码。你问“11月9日日历上有什么”，Agent自己决定调用get_events、读取结果、用自然语言回答——你从没告诉它该调哪个函数。

同样的模式适用于任何场景：读邮件并起草回复、查询订单、更新表格。对于发送邮件这类有风险的操作，让它只写草稿，由人来按下发送键。

联网搜索与脱离笔记本运行

Agent只懂训练数据，除非你让它搜索。Web search工具内置于SDK，导入后加入工具列表，并要求Agent为每个论点附上来源链接。但链接仍要自己点开核实——搜索让答案更新鲜，不是更正确。

成本方面：每条消息、每个工具结果、每次搜索都消耗token，而token就是计费单位。指令简短、工具结果简短能压低成本，消费上限是安全网。

最后一个问题：笔记本休眠Agent就停了。免费方案是用GitHub Actions——把项目推到GitHub，API Key存为仓库secret，添加一个workflow文件，cron行设定时间表，Actions标签页能看到每次运行和输出。

GitHub Actions 是 GitHub 提供的 CI/CD 服务，允许在仓库中定义自动化工作流。工作流由 .github/workflows/ 下的 YAML 文件描述，其中 on.schedule.cron 字段使用 cron 语法设定定时触发（如 0 9 * * * 表示每天 UTC 9 点）。运行环境是 GitHub 提供的临时虚拟机，每次执行完毕后销毁，因此适合无状态任务。敏感信息（如 API Key）应存为仓库的 Secrets，在工作流中通过 ${{ secrets.OPENAI_API_KEY }} 引用，不会暴露在日志中。免费账户每月有一定额度，个人定时任务通常够用。注意 cron 使用 UTC 时区，需换算成本地时间。

新手最常见的四个报错

• No module named agents：虚拟环境没激活，或包装到了别处。激活环境后重装。
• Missing credentials：当前终端读不到环境变量，重新设置；Windows上设置后要开新终端。
• 错误码429：请求太快，或账户余额不足。检查账单和限额。
• Python不被识别：Mac用python3；Windows重跑安装程序并勾选Add Python to path。

卡住时先读报错的最后一行，它通常直接告诉你问题在哪。

你构建了什么

回顾一下：装好Python和VS Code、守住API Key、写出Agent、用session给它记忆、用一个装饰器给它工具、接入网页搜索、了解了定时运行的方法。这套模式可以复用到几乎任何任务。下一步是把它跑起来，然后想想：你给Agent的第一个工具会是什么？