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 核心逻辑不依赖具体模型厂商。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

搭建 Python 工程

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通