1. Agent 运行环境检查与依赖安装
Agent 部署的第一步是建立可复现、无冲突的运行环境。操作系统、Python 解释器版本、底层系统库（如 GCC、OpenSSL）以及包管理器的配置直接决定后续模块能否正确编译和加载。在分布式多节点部署场景下，环境差异是故障的主要源头，因此本章将环境检查前置为“部署边界”的第一道门禁。
核心原则：在安装任何 Python 包之前，先确认操作系统类型与发行版、Python 小版本号（≥3.9）、pip 版本（≥21.3），以及是否设置了正确的 pip 源。
1.1 操作系统确认
Agent 大多数基于 Linux 构建，Windows 和 macOS 通常仅在开发或单机调试中出现。以下命令用于快速获取发行版信息：
# 查看内核版本（所有 Linux 通用）
uname -r
# 查看发行版名称与版本号
cat /etc/os-release
# 或使用 lsb_release（需安装 redhat-lsb-core）
lsb_release -a| 发行版 | 推荐内核版本 | 注意事项 |
|---|---|---|
| Ubuntu 22.04 / 24.04 | ≥ 5.15 | 默认源已包含 Python 3.10+，可直接安装 |
| Debian 12 | ≥ 6.1 | 需先 apt update，确保 glibc ≥ 2.36 |
| CentOS 7 / Rocky 9 | ≥ 3.10 / 5.14 | CentOS 7 需额外安装 EPEL 源和 devtoolset |
| Alpine 3.18+ | ≥ 6.2 | 使用 musl libc，部分 wheel 需从源码编译 |
避坑：不要在生产环境使用 EOL（End of Life）操作系统，例如 CentOS 7 已于 2024 年 6 月停止维护。继续使用将无法获得安全补丁，且 pip 源中很多 Wheel 包已不再针对这些旧版本的 glibc 构建。
1.2 Python 版本校验
Agent 依赖异步 I/O、类型注解和最新语言特性，要求 Python 版本 ≥ 3.9。建议统一使用 3.10 或 3.11 以获得最佳兼容性和性能。执行以下检查：
python3 --version
# 输出示例：Python 3.10.12
# 若版本低于 3.9，需手动升级或使用 conda 管理
# Ubuntu 示例
sudo apt update && sudo apt install python3.10 python3.10-venv python3.10-dev -y
# CentOS / Rocky 示例
sudo yum install -y epel-release
sudo yum install -y python3.11 python3.11-devel1.3 pip 配置源与版本检查
国内网络环境强烈建议配置清华大学或阿里云镜像源，避免因 PyPI 官网不稳定导致的依赖安装超时。
# 查看当前 pip 版本
pip3 --version
# 升级 pip
python3 -m pip install --upgrade pip
# 配置全局 pip 源（写入 ~/.config/pip/pip.conf 或 /etc/pip.conf）
mkdir -p ~/.config/pip
cat > ~/.config/pip/pip.conf << 'EOF'
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF1.4 依赖包列表与安装
Agent 核心依赖包括异步框架、序列化、网络通信、向量计算和 LLM 客户端。一个典型的 requirements.txt 如下：
# requirements.txt
aiohttp>=3.9,<4
pydantic>=2.5
numpy>=1.24
httpx>=0.27
jsonschema>=4.20
openai>=1.12
pydantic-settings>=2.1
python-dotenv>=1.0
loguru>=0.7
orjson>=3.9安装命令：
python3 -m pip install -r requirements.txt如果项目包含 C 扩展（如 tokenizers、bitsandbytes），需要确保系统已安装对应编译工具：
# Ubuntu / Debian
sudo apt install build-essential cmake
# CentOS / Rocky
sudo yum groupinstall "Development Tools"
sudo yum install cmake1.5 环境检查流程
下面的 SVG 流程图总结了从裸机到可运行 Agent 的标准化环境检查流程，也是后续章节“配置边界”的第一道关卡。
1.6 调试与常见错误
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
ERROR: Could not find a version that satisfies the requirement X | pip 源未更新或找不到对应包 | 切换源至清华/阿里，或使用 --extra-index-url |
Failed to build wheel for Y | 缺少编译依赖（如 gcc、python3-dev） | 安装对应系统包：sudo apt install python3-dev build-essential |
Python 3.8 is not supported | Python 版本过低 | 使用 pyenv 或 conda 创建 3.10+ 环境 |
Could not find platform independent libraries <prefix> | Python 安装不完整或环境变量缺失 | 重新安装 Python，检查 LD_LIBRARY_PATH 和 PYTHONHOME |
HTTPSConnectionPool: Read timed out | 网络问题导致 PyPI 访问超时 | 设置超时选项：pip install --default-timeout=120，并更换国内源 |
1.7 调试与验证
完成依赖安装后，执行一段简易脚本验证核心模块是否可正确加载：
python3 -c "
import aiohttp
import pydantic
import httpx
import numpy
import loguru
print('All core dependencies loaded successfully.')
print(f'aiohttp: {aiohttp.__version__}')
print(f'pydantic: {pydantic.__version__}')
"若输出正确且无 ImportError，则环境准备阶段通过；否则返回前面的步骤检查系统库和 pip 源配置。该验证手段应写入项目的 CI/CD 流程，作为部署 gate 的第一步。