Agent/docs/dependencies.md

Agent Framework 依赖管理

📦 核心依赖

必需依赖

包名	版本	用途
httpx[socks]	>=0.28.0	HTTP 客户端，用于调用 Gemini REST API，支持 SOCKS 代理
python-dotenv	>=1.0.0	环境变量管理，用于加载 .env 配置文件

可选依赖

包名	版本	用途	安装建议
docstring-parser	>=0.15	工具文档解析，提供更好的类型提示和描述解析	推荐安装
google-generativeai	>=0.8.0	Google Gemini SDK（不推荐使用）	❌ 不推荐，使用 HTTP API 代替

🚀 安装方式

方式一：使用 requirements.txt（推荐）

pip install -r requirements.txt

方式二：手动安装

# 安装核心依赖
pip install httpx[socks]>=0.28.0 python-dotenv>=1.0.0

# 可选：安装 docstring-parser
pip install docstring-parser>=0.15

方式三：使用 pip 直接安装

pip install httpx[socks] python-dotenv

📝 依赖说明

httpx[socks]

• 用途：异步 HTTP 客户端，用于调用 Gemini REST API
• 为什么需要 [socks]：支持 SOCKS 代理（很多用户需要代理访问 Google API）
• 如果不需要代理：可以只安装 httpx，但推荐安装完整版

python-dotenv

• 用途：从 .env 文件加载环境变量

• 配置示例：

  # .env
  GEMINI_API_KEY=your_api_key_here
  

  docstring-parser（可选）

  • 用途：解析工具函数的 docstring，提取参数类型和描述
  • 如果没安装：框架会使用 fallback 解析器，功能稍弱但可用
  • 推荐理由：提供更准确的工具 schema 生成

  google-generativeai（不推荐）

  • 为什么不推荐：
  • SDK 对 JSON Schema 格式要求严格，与 OpenAI 工具格式不完全兼容
  • 难以调试和自定义
  • HTTP API 提供更好的控制和灵活性
  • 何时使用：仅用于学习或简单场景

  🔧 开发依赖

  如果你要开发或测试框架，还需要：

  # 测试框架
  pip install pytest pytest-asyncio
  
  # 代码质量
  pip install black flake8 mypy
  
  # 文档生成
  pip install mkdocs mkdocs-material
  

🌐 Python 版本要求

• 最低版本：Python 3.9
• 推荐版本：Python 3.11+
• 兼容性：
  • ✅ Python 3.9+
  • ✅ Python 3.10
  • ✅ Python 3.11
  • ✅ Python 3.12

📋 依赖检查

运行以下命令检查依赖是否正确安装：

python3 -c "
import httpx
import dotenv
print('✅ 核心依赖安装成功')

try:
    import docstring_parser
    print('✅ docstring-parser 已安装')
except ImportError:
    print('⚠️  docstring-parser 未安装（可选）')
"

🐛 常见问题

Q1: 安装 httpx 时报错 "No module named 'socksio'"

解决方案：

pip install 'httpx[socks]'

Q2: ImportError: cannot import name 'AsyncClient' from 'httpx'

解决方案：升级 httpx 到最新版本

pip install --upgrade httpx

Q3: 代理设置

如果你使用代理，在 .env 中配置：

HTTP_PROXY=socks5://127.0.0.1:7890
HTTPS_PROXY=socks5://127.0.0.1:7890

或者在代码中设置：

import httpx

client = httpx.AsyncClient(
    proxies={
        "http://": "socks5://127.0.0.1:7890",
        "https://": "socks5://127.0.0.1:7890"
    }
)

📦 生成 requirements.txt

如果你修改了依赖，可以重新生成：

# 导出当前环境所有包（不推荐）
pip freeze > requirements-full.txt

# 手动维护 requirements.txt（推荐）
# 只包含项目直接依赖，不包括子依赖

🔄 更新依赖

# 更新所有依赖到最新版本
pip install --upgrade -r requirements.txt

# 更新特定包
pip install --upgrade httpx

🎯 最小化依赖原则

本框架遵循最小化依赖原则：

• ✅ 只依赖必需的包
• ✅ 避免大型框架（如 Django, FastAPI）
• ✅ 使用标准库优先（asyncio, json, logging）
• ✅ 可选依赖明确标注

📊 依赖关系图

agent/
├── httpx (必需)
│   ├── httpcore
│   ├── certifi
│   ├── idna
│   └── socksio (SOCKS 代理支持)
│
├── python-dotenv (必需)
│
└── docstring-parser (可选)

🌟 生产环境建议

生产环境推荐固定版本：

# requirements-prod.txt
httpx[socks]==0.28.1
python-dotenv==1.2.1
docstring-parser==0.16

使用：

pip install -r requirements-prod.txt

📚 相关文档

• httpx 文档
• python-dotenv 文档
• docstring-parser 文档
• Gemini API 文档