Agent 开发之路

主题

环境准备 ​

🎯 难度：入门⏱ 预计：30 分钟# uv# VS Code# API Key

这一节我们一次性把开发环境配好：Python + 包管理器 + 编辑器 + 大模型 API Key。

一、安装 uv（Python 界的 pnpm） ​

Python 的工具链历史上比较混乱（pip、venv、conda、poetry……），新手很容易被劝退。好消息是现在有了 uv：一个用 Rust 写的、极快的「一站式」工具，它能帮你：

  • 安装和管理 Python 版本（类似 nvm）
  • 创建项目、管理依赖（类似 pnpm）
  • 运行脚本（类似 npx / npm run）
bash
curl -LsSf https://astral.sh/uv/install.sh | sh
powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
bash
brew install uv

安装后重新打开终端，验证一下：

bash
uv --version
# uv 0.x.x

二、安装 Python ​

用 uv 安装 Python，一条命令搞定（不需要去官网下载安装包）：

bash
uv python install 3.12

为什么是 3.12？

3.12 / 3.13 都是稳定且被 AI 库广泛支持的版本。太新的版本有时候部分库还没适配，所以我们选 3.12 作为教程的统一版本。

macOS 用户注意

macOS 自带了一个 python3（通常是比较老的 3.9），不要用它，也不要动它。我们始终通过 uv run 来运行代码，uv 会自动使用正确的 Python 版本。

三、npm → uv 对照表 ​

作为前端，你可以这样理解 uv：

你想做的事npm / pnpmuv
初始化项目npm inituv init
安装依赖npm install axiosuv add httpx
安装开发依赖npm install -D eslintuv add --dev ruff
卸载依赖npm uninstall axiosuv remove httpx
根据锁文件装全部依赖npm ciuv sync
运行脚本node index.jsuv run main.py
依赖清单文件package.jsonpyproject.toml
锁文件package-lock.jsonuv.lock
依赖安装目录node_modules/.venv/
临时运行一个工具npx xxxuvx xxx

.venv 叫做「虚拟环境」，它就是 Python 版的 node_modules：每个项目的依赖装在自己的 .venv 里，互不干扰。记得把它加进 .gitignore（uv 会自动帮你做）。

四、创建你的第一个项目 ​

bash
uv init agent-lab
cd agent-lab

uv 会生成这样的结构：

text
agent-lab/
├── .gitignore
├── .python-version   # 锁定 Python 版本，类似 .nvmrc
├── README.md
├── main.py           # 入口文件
└── pyproject.toml    # 类似 package.json

看看 main.py：

python
def main():
    print("Hello from agent-lab!")


if __name__ == "__main__":
    main()

运行它：

bash
uv run main.py
# Hello from agent-lab!

🎉 恭喜，你的第一行 Python 跑起来了！

什么是 if __name__ == "__main__":？

这是 Python 的一个惯用写法，意思是「只有当这个文件被直接运行时才执行 main()；如果它被别的文件 import，就不执行」。

类比 JS：有点像 Node.js 里的 if (require.main === module)。现在你只需要知道它是「程序入口」的标准写法即可。

五、配置 VS Code ​

推荐使用 VS Code（或 Cursor / Qoder 等基于 VS Code 的编辑器），安装这两个扩展：

扩展作用前端类比
Python（Microsoft 出品，会自动附带 Pylance）语法高亮、智能补全、类型检查、调试TypeScript 语言服务
Ruff代码格式化 + Lint，极快Prettier + ESLint

然后在项目根目录创建 .vscode/settings.json：

json
{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  },
  "python.analysis.typeCheckingMode": "basic"
}

选择解释器

用 VS Code 打开项目后，按 Cmd/Ctrl + Shift + P，输入 Python: Select Interpreter，选择项目里的 .venv。这样编辑器才能正确识别你安装的库，提供代码补全。 （如果还没有 .venv，先执行一次 uv sync 或 uv add 任意一个包就会自动创建。）

六、获取大模型 API Key ​

Agent 的「大脑」是大模型，我们需要通过 API 调用它。本教程的所有代码都使用 OpenAI 兼容接口——这是业界事实标准，国内外绝大多数模型平台都支持。你只需选一家注册即可：

平台base_url模型名示例说明
DeepSeekhttps://api.deepseek.comdeepseek-chat便宜、能力强，推荐新手首选
阿里云百炼（通义千问）https://dashscope.aliyuncs.com/compatible-mode/v1qwen-plus新用户免费额度多，还提供 Embedding 模型
Moonshot（Kimi）https://api.moonshot.cn/v1以控制台为准长上下文
OpenAIhttps://api.openai.com/v1以控制台为准需要海外网络和支付方式

模型名会更新

大模型迭代非常快，模型名称经常更新。上表的 base_url 比较稳定，模型名请以各平台控制台/文档为准。

关于 Embedding 模型

第三阶段的 RAG 章节需要用到「Embedding（向量化）模型」。DeepSeek 目前不提供 Embedding 接口，到时候你可以额外注册一个通义千问（text-embedding-v3）或 OpenAI（text-embedding-3-small）。现在先不用管。

把 Key 存进 .env ​

永远不要把 API Key 写死在代码里！ 和前端项目一样，我们使用 .env 文件。在项目根目录创建 .env：

bash
# .env —— 以 DeepSeek 为例
LLM_API_KEY=sk-xxxxxxxxxxxxxxxx
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-chat

并确认 .gitignore 中有 .env：

bash
echo ".env" >> .gitignore

安全提醒

API Key 泄露 = 别人用你的钱。提交代码前务必检查 .env 没有被 git 追踪。如果不小心泄露了，立刻去平台控制台删除这个 Key 并重新生成。

七、验证：让大模型跟你打个招呼 ​

安装两个依赖：

bash
uv add "openai>=1.68,<2" "python-dotenv>=1,<2"

把 main.py 改成：

python
import os

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()  # 读取 .env 文件到环境变量

client = OpenAI(
    api_key=os.getenv("LLM_API_KEY"),
    base_url=os.getenv("LLM_BASE_URL"),
)

response = client.chat.completions.create(
    model=os.getenv("LLM_MODEL"),
    messages=[{"role": "user", "content": "用一句话向一位前端工程师打个招呼"}],
)

print(response.choices[0].message.content)

运行：

bash
uv run main.py

如果你看到大模型的回复，说明一切就绪！🎉 这段代码现在看不懂完全没关系，我们会在第二阶段逐行讲解。

常见报错排查
  • ModuleNotFoundError: No module named 'openai'：没有用 uv run 运行，或者没执行 uv add openai。
  • AuthenticationError / 401：API Key 不对，检查 .env 是否在项目根目录、有没有多余空格或引号。
  • NotFoundError / 404：base_url 或模型名写错了。
  • 连接超时：检查网络；使用 OpenAI 需要海外网络环境。

小结 ​

  • ✅ 用 uv 管理 Python 版本和依赖，它就是 Python 界的 nvm + pnpm
  • ✅ .venv ≈ node_modules，pyproject.toml ≈ package.json
  • ✅ 始终用 uv run xxx.py 运行代码
  • ✅ API Key 放在 .env，绝不提交到 git

环境准备完毕，开始我们的 Python 速成之旅吧 → 给前端的 Python 导读

用心写给每一个想入门 Agent 开发的前端工程师

© Agent 开发之路