3. 智能体架构概览
说实话，很多初学者在搭建环境这一步就栽了跟头。我见过太多人花了一周时间配置环境，结果代码还没写一行。别急，咱们一步步来。
智能体开发说白了就是Python开发。但这里有个坑——Python版本管理。你想想看，一个项目用Python 3.8，另一个用3.11，如果全装系统里，迟早出问题。我当年就吃过这个亏，一个项目跑着跑着突然报错，查了半天发现是系统Python版本被另一个项目覆盖了。
3.1 Python版本管理：pyenv
我的建议是，别碰系统自带的Python。用pyenv来管理多版本，干净又安全。
核心思路：pyenv让你在同一台机器上安装多个Python版本，随时切换，互不干扰。
安装pyenv（macOS/Linux）
# macOS
brew install pyenv
# Linux
curl https://pyenv.run | bash
# 配置shell环境（以bash为例）
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc常用命令速查
| 命令 | 说明 |
|---|---|
pyenv install --list |
查看可安装的Python版本 |
pyenv install 3.11.5 |
安装指定版本 |
pyenv versions |
列出已安装的所有版本 |
pyenv global 3.11.5 |
设置全局默认版本 |
pyenv local 3.10.12 |
在当前目录设置局部版本（会生成.python-version文件） |
我的习惯：每个项目根目录都执行一次pyenv local，这样团队成员clone代码后自动切换到正确版本。省心。
3.2 虚拟环境管理：venv & virtualenvwrapper
有了pyenv管理Python版本，接下来要解决包隔离的问题。虚拟环境就是干这个的——每个项目有自己的小天地，依赖互不打架。
Python 3.3+自带venv模块，够用。但我个人更推荐virtualenvwrapper，它让虚拟环境的管理变得像呼吸一样自然。
安装与配置
# 安装virtualenvwrapper
pip install virtualenvwrapper
# 配置shell（以bash为例）
export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_PYTHON=$(which python3)
source $(which virtualenvwrapper.sh)日常操作
# 创建虚拟环境（指定Python版本）
mkvirtualenv agent-dev -p python3.11
# 激活环境
workon agent-dev
# 退出环境
deactivate
# 列出所有环境
lsvirtualenv
# 删除环境
rmvirtualenv agent-dev我曾经踩过的坑：创建虚拟环境时忘了指定-p参数，结果用了系统默认的Python 2.7。装了一堆包才发现版本不对。所以，每次创建环境都显式指定Python版本，养成习惯。
3.3 依赖管理：pip vs poetry
依赖管理是智能体开发的重头戏。一个智能体项目少说几十个依赖，多则上百。怎么管？
传统做法是pip + requirements.txt。简单直接，但有个致命问题——它不区分直接依赖和间接依赖。你装A包，A又装了B和C，最后pip freeze出来一堆包，你根本分不清哪些是项目真正需要的。
所以我推荐poetry。它用pyproject.toml记录直接依赖，用poetry.lock锁定完整依赖树。干净、可复现。
安装poetry
curl -sSL https://install.python-poetry.org | python3 -项目初始化
# 创建新项目
poetry new agent-project
# 或在已有项目中初始化
cd existing-project
poetry init依赖管理对比
| 特性 | pip + requirements.txt | poetry |
|---|---|---|
| 依赖声明 | 手动维护requirements.txt | 自动写入pyproject.toml |
| 依赖锁定 | pip freeze > requirements-lock.txt | 自动生成poetry.lock |
| 直接/间接依赖 | 不区分 | 清晰区分 |
| 虚拟环境 | 需手动创建 | 自动管理 |
| 发布包 | 需额外工具 | 内置build/publish |
poetry常用命令
# 添加依赖
poetry add langchain
# 添加开发依赖
poetry add --dev pytest black
# 安装所有依赖
poetry install
# 更新依赖
poetry update
# 导出requirements.txt（给CI用）
poetry export -f requirements.txt --output requirements.txt我的建议：团队项目用poetry，个人小项目用pip。但如果你做智能体开发，迟早要面对复杂的依赖树，不如一开始就用poetry。
3.4 版本控制：Git基础
版本控制是开发者的基本功。智能体开发涉及大量实验性代码，没有Git，你根本没法回溯、对比、协作。
我不打算讲Git的所有命令，只讲智能体开发中最常用的几个场景。
初始化与基本操作
# 初始化仓库
git init
# 添加文件到暂存区
git add .
# 提交
git commit -m "feat: 初始化智能体项目结构"
# 查看状态
git status
# 查看提交历史
git log --oneline --graph.gitignore配置
智能体项目有些文件不该进版本控制。比如、模型权重、虚拟环境等。
# Python
__pycache__/
*.py[cod]
*.so
# 虚拟环境
.venv/
venv/
# IDE
.vscode/
.idea/
# 智能体相关
.env
*.pkl
*.h5
checkpoints/
logs/
# 依赖锁定（如果用poetry，poetry.lock要提交）
# poetry.lock血的教训：我曾经把的提交到了公开仓库，几分钟后就收到账单提醒——有人用我的key调了上千次接口。从那以后，我每次提交前都用git diff --cached检查一遍，确保没有敏感信息。
分支策略
智能体开发建议用功能分支模式：
main：稳定版本，只合入经过测试的代码dev：开发主分支，日常集成feature/xxx：新功能分支，比如feature/agent-memoryfix/xxx：修复分支
# 创建功能分支
git checkout -b feature/agent-tools
# 开发完成后合并到dev
git checkout dev
git merge feature/agent-tools
# 删除功能分支
git branch -d feature/agent-tools3.5 完整环境搭建流程
说了这么多，咱们串起来走一遍。假设你要开始一个智能体项目：
- 安装pyenv，安装Python 3.11.5
- 创建项目目录，执行
pyenv local 3.11.5 - 安装poetry，执行
poetry init - 添加核心依赖：
poetry add langchain chromadb - 初始化Git：
git init，配置.gitignore - 首次提交：
git add . && git commit -m "chore: 初始化项目环境"
我的习惯：把上面这些步骤写成Makefile或shell脚本，新项目直接跑一遍。省时省力，还不会漏步骤。
3.6 知识体系总览
下面这张图把本章的核心逻辑串起来了。你可以把它当作环境搭建的路线图：
环境搭建看起来琐碎，但它是智能体开发的基石。我见过太多项目死在环境问题上——依赖冲突、版本不兼容、缺少关键包。花半小时把环境搭好，后面能省下数倍的时间。