AI Agent / 系统课时
搭建 Python 工程
搭建 Python 工程
本节解决 Agent 项目从零开始时工程结构混乱、依赖不可控和配置难维护的问题。通过 Python 3.13+ 建立规范化项目骨架,最终得到可运行、可测试、便于扩展 Agent Core 的开发基础。
学习目标
- 掌握 Python Agent 项目的基础目录规划与虚拟环境管理方式。
- 学会使用依赖文件和配置分层控制工程运行环境。
- 能够搭建包含源码、测试和配置的最小可维护工程。
创建 Python 项目基础环境
Agent 工程通常会包含模型调用、工具执行、状态管理、测试验证等多个模块。如果直接在系统 Python 中安装依赖,容易出现版本冲突,因此第一步应建立独立虚拟环境。
Python 3.13+ 推荐使用 venv 创建轻量隔离环境,并通过依赖文件记录项目需要的软件包。
bash
mkdir agent-project
cd agent-project
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip预期输出
text
Successfully installed pip
(.venv) 当前终端进入虚拟环境虚拟环境只解决运行隔离问题,工程结构还需要明确划分职责。
规划 Agent 工程目录
一个基础 Agent 项目通常将业务代码放入源码目录,将验证代码放入测试目录,将运行参数放入配置目录。
推荐结构如下:
text
agent-project/
├── src/
│ └── agent/
│ ├── core/
│ ├── models/
│ ├── tools/
│ └── config/
├── tests/
├── pyproject.toml
├── .env
└── README.md其中:
core保存 Agent 推理循环、任务编排等核心逻辑。models保存模型访问封装。tools保存外部能力调用。config保存配置加载逻辑。tests验证核心模块行为。
这种划分可以避免模型调用、业务流程和环境配置互相耦合。
使用依赖管理描述工程
现代 Python 项目通常使用 pyproject.toml 作为工程入口,统一描述项目元数据和依赖。
toml
[project]
name = "agent-project"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
"pydantic>=2.0",
"httpx>=0.27"
]预期结果
text
项目可以根据 pyproject.toml 恢复指定 Python 依赖环境实际项目中,生产环境还应结合锁定文件固定依赖版本,避免不同机器安装出不同结果。
设计配置分层
Agent 工程通常同时存在开发、测试和生产环境,因此配置不能直接写死在代码中。
推荐将配置来源分为三层:
| 配置类型 | 示例 | 作用 |
|---|---|---|
| 默认配置 | 代码中的默认值 | 提供基础行为 |
| 环境变量 | API Key、地址 | 区分部署环境 |
| 本地配置文件 | 开发参数 | 提升开发效率 |
例如模型密钥不应直接写入源码:
python
import os
MODEL_API_KEY = os.getenv("MODEL_API_KEY")
if not MODEL_API_KEY:
raise RuntimeError("缺少 MODEL_API_KEY")预期输出
text
环境变量存在时继续启动
缺少配置时抛出明确错误验证工程是否可用
完成基础搭建后,应验证环境、依赖和测试入口是否正常。
bash
python --version
pip list
pytest预期输出
text
Python 3.13.x
已安装项目依赖
测试通过常见问题包括虚拟环境未激活、Python 版本不符合要求以及依赖安装位置错误。排查时优先确认当前解释器路径:
bash
which python预期输出
text
<PATH>/agent-project/.venv/bin/python本课总结
- Python Agent 工程应先建立隔离环境,再组织源码、配置和测试目录。
pyproject.toml与分层配置能够降低依赖和部署风险。- 清晰目录边界是后续扩展模型、工具和 Agent Core 的基础。
下一课预告
下一节将设计模型接入层,通过统一客户端和 Provider Adapter 隔离不同模型服务差异,让 Agent 核心逻辑不依赖具体模型厂商。
按自己的节奏,确认真正理解。