Python Agent Environment Configuration

Before starting to build an AI Agent, we need to set up a suitable development environment.

Python is the most popular language in the fields of AI and machine learning, with rich library and tool support.

1. Python Version Selection

For AI Agent development, we recommend usingPython 3.9 or higher。

The following versions are common choices:

• Python 3.9: Good stability, best compatibility
• Python 3.10: Performance improvements, new features
• Python 3.11+: Latest version, best performance

Note: Some libraries may have specific requirements for Python versions; it is recommended to check the official documentation.

2. Installing Python

Windows System

• VisitPython official website
• Download the latest Python installer (3.9 or higher)
• Run the installer,Be sure to checkAdd Python to PATH
• After installation is complete, open Command Prompt (CMD) or PowerShell, and enter:python --version, the Python version number should be displayed.

macOS System

macOS usually comes with Python pre-installed, but it may be an old version. It is recommended to install using Homebrew:

# 安装 Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Python
brew install [email protected]

# 验证安装
python3 --version

Linux System

Most Linux distributions come with Python pre-installed. If you need a specific version:

# Ubuntu/Debian
sudo apt update
sudo apt install python3.9 python3-pip

# CentOS/RHEL
sudo yum install python39 python39-pip

# 验证安装
python3 --version

3. Virtual Environment Configuration

Using a virtual environment can isolate dependencies of different projects and avoid version conflicts.

Creating a Virtual Environment

# 创建项目目录
mkdir ai-agent-project
cd ai-agent-project

Use uv to create and activate a virtual environment. For more details, you can readuv Tutorial。

Install uv

pip install uv

Create using the uv command:

# 创建名为 .venv 的虚拟环境（默认）
uv venv

# 激活环境（macOS/Linux）
source .venv/bin/activate

# 激活环境（Windows）
.venv\Scripts\activate

Other tools:

# 使用 venv，Python 3.3+ 内置
python -m venv venv

# 或使用 conda（如果已安装 Anaconda/Miniconda）
conda create -n ai-agent python=3.9
conda activate ai-agent

Activating the Virtual Environment

Windows：

venv\Scripts\activate

macOS/Linux：

source venv/bin/activate

After activation, the command line prompt usually displays the virtual environment name (e.g.,(venv)）。

Exiting the Virtual Environment

deactivate

4. Package Management Tool pip

pip is Python's package management tool, used to install third-party libraries.

Common Commands：

# 升级 pip 到最新版本
pip install --upgrade pip

# 安装包
pip install package_name

# 安装特定版本
pip install package_name==1.2.3

# 从 requirements.txt 安装所有依赖
pip install -r requirements.txt

# 列出已安装的包
pip list

# 生成 requirements.txt
pip freeze > requirements.txt

5. Recommended Development Directory Structure

A good project structure helps with code management and maintenance:

ai-agent-project/
├── .env                    # 环境变量文件（不提交到Git）
├── .gitignore             # Git忽略文件
├── requirements.txt       # 项目依赖
├── README.md             # 项目说明
├── src/                  # 源代码目录
│   ├── __init__.py
│   ├── agents/          # Agent相关代码
│   │   ├── __init__.py
│   │   ├── base_agent.py
│   │   └── weather_agent.py
│   ├── tools/           # 工具定义
│   │   ├── __init__.py
│   │   ├── calculator.py
│   │   └── web_search.py
│   ├── memory/          # 记忆系统
│   │   ├── __init__.py
│   │   ├── short_term.py
│   │   └── vector_memory.py
│   └── utils/           # 工具函数
│       ├── __init__.py
│       ├── config.py
│       └── logger.py
├── tests/               # 测试代码
│   ├── __init__.py
│   ├── test_agents.py
│   └── test_tools.py
├── examples/            # 示例代码
│   ├── basic_agent.py
│   └── multi_tool_agent.py
└── notebooks/           # Jupyter笔记本
    └── experiments.ipynb

Installing Essential Libraries

AI Agent development requires support from a series of third-party libraries. Below are the installation methods and brief introductions for the core libraries.

Installing Core Libraries

Createrequirements.txtfile, containing the following content:

# 基础库
python-dotenv>=1.0.0      # 环境变量管理
pydantic>=2.0.0           # 数据验证和设置管理
loguru>=0.7.0             # 日志记录

# AI/ML 相关
openai>=1.0.0             # OpenAI API
anthropic>=0.7.0          # Claude API
google-generativeai>=0.3.0 # Gemini API
sentence-transformers>=2.2.0 # Embedding 模型
chromadb>=0.4.0           # 向量数据库

# Agent 框架
langchain>=0.1.0          # LangChain 框架
langchain-community>=0.0.10 # LangChain 社区工具
langchain-openai>=0.0.5   # LangChain OpenAI 集成
llama-index>=0.10.0       # LlamaIndex（可选）
semantic-kernel>=0.9.0    # Semantic Kernel（可选）

# 工具和工具
requests>=2.31.0          # HTTP 请求
beautifulsoup4>=4.12.0    # HTML 解析
pandas>=2.0.0             # 数据处理
numpy>=1.24.0             # 数值计算

# 开发工具
pytest>=7.4.0             # 测试框架
black>=23.0.0             # 代码格式化
flake8>=6.0.0             # 代码检查
jupyter>=1.0.0            # Jupyter 笔记本

Install all dependencies:

pip install -r requirements.txt

Introduction to Major Libraries

1. LangChain

LangChain is the most popular AI Agent development framework, providing tools for building chain (Chain) and agent (Agent) applications.

# LangChain 基本使用示例
from langchain.llms import OpenAI
from langchain.chat_models import ChatOpenAI
from langchain.agents import initialize_agent, AgentType
from langchain.tools import Tool

# 初始化 LLM
llm = ChatOpenAI(temperature=0.7, model="gpt-3.5-turbo")

# 创建工具
tools = [
    Tool(
        name="计算器",
        func=lambda x: str(eval(x)),
        description="用于数学计算"
    )
]

# 创建 Agent
agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# 运行 Agent
result = agent.run("计算 25 的平方根")
print(result)

2. LlamaIndex

LlamaIndex (formerly GPT Index) focuses on document indexing and retrieval, suitable for building document-based Q&A systems.

# LlamaIndex 基本使用示例
from llama_index import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms import OpenAI

# 加载文档
documents = SimpleDirectoryReader("./data").load_data()

# 创建索引
index = VectorStoreIndex.from_documents(documents)

# 创建查询引擎
query_engine = index.as_query_engine()

# 查询
response = query_engine.query("文档中提到了哪些AI技术？")
print(response)

3. Semantic Kernel

Semantic Kernel is a framework launched by Microsoft, emphasizing extensibility and enterprise-grade applications.

# Semantic Kernel 基本使用示例
import semantic_kernel as sk
from semantic_kernel.connectors.ai.open_ai import OpenAITextCompletion

# 初始化内核
kernel = sk.Kernel()
api_key = "your-openai-api-key"
kernel.add_text_completion_service(
    "dv",
    OpenAITextCompletion("text-davinci-003", api_key)
)

# 定义技能
skill = kernel.import_semantic_skill_from_directory("./skills", "ExampleSkill")

# 运行技能
context = kernel.create_new_context()
context["input"] = "介绍一下人工智能"
result = skill["Summarize"](context)
print(result)

Installation Verification

Create a verification scriptverify_installation.py：

Run verification:

python verify_installation.py

Troubleshooting Common Installation Issues

1. Slow installation or timeout

# 使用国内镜像源
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或使用阿里云镜像
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

2. Version conflicts

# 创建新的虚拟环境
python -m venv new_venv
source new_venv/bin/activate  # 或 venv\Scripts\activate

# 重新安装，让 pip 自动解决依赖
pip install --upgrade pip
pip install langchain openai

3. Specific platform issues (e.g., Apple Silicon)

# 对于 Apple Silicon (M1/M2/M3)，可能需要特定版本
pip install grpcio==1.48.2  # 解决某些兼容性问题

# 或使用 conda
conda install -c conda-forge grpcio

API Key Management

AI Agent development requires access to various API services (such as OpenAI, Anthropic, DeepSeek, etc.). Securely and effectively managing API keys is crucial.

1. Why Do You Need to Manage API Keys Securely?

• Prevent leaks: API Key leaks can lead to financial losses
• Access control: Use different keys in different environments
• Easy configuration: Unified configuration method for team collaboration
• Environment isolation: Use different keys for development, testing, and production environments

2. Environment Variable Management (Recommended)

Use.envManage sensitive information with files; do not commit to version control.

Create.envFile

# API Keys
OPENAI_API_KEY=sk-你的OpenAI密钥
ANTHROPIC_API_KEY=你的Claude密钥
GOOGLE_API_KEY=你的Gemini密钥
SERPAPI_API_KEY=你的搜索API密钥

# 应用配置
APP_ENV=development
LOG_LEVEL=INFO
DEBUG=true

# 数据库配置（如使用）
VECTOR_DB_PATH=./data/vector_db
MAX_MEMORY_ITEMS=1000

Create.gitignoreFile

Ensure.envFiles are not committed to Git:

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
venv/
ENV/
env.bak/
venv.bak/

# 环境变量
.env
.env.local
.env.*.local

# 数据文件
data/
*.db
*.sqlite
*.sqlite3

# 日志
logs/
*.log

# 编辑器
.vscode/
.idea/
*.swp
*.swo

Load environment variables using python-dotenv

3. Using API Keys Securely

Use environment variables in code

import os
from openai import OpenAI

# 从环境变量读取 API Key
api_key = os.getenv("OPENAI_API_KEY")

if not api_key:
    raise ValueError("OPENAI_API_KEY 环境变量未设置")

# 初始化 OpenAI 客户端
client = OpenAI(api_key=api_key)

# 使用客户端
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "你好"}]
)

Use a configuration class

4. Multi-Environment Configuration

For large projects, different environment configurations may be needed:

Environment-specific.envFile

# .env.development (开发环境)
OPENAI_API_KEY=sk-dev-key
APP_ENV=development
DEBUG=true

# .env.production (生产环境)
OPENAI_API_KEY=sk-prod-key
APP_ENV=production
DEBUG=false

Dynamically load environment configuration

# config_manager.py
import os
from pathlib import Path
from dotenv import load_dotenv

class ConfigManager:
    """配置管理器"""

    def __init__(self, env=None):
        self.env = env or os.getenv("APP_ENV", "development")
        self.load_config()

    def load_config(self):
        """加载配置"""
        # 先加载通用配置
        load_dotenv(dotenv_path=Path('.') / '.env')

        # 加载环境特定配置
        env_file = Path('.') / f'.env.{self.env}'
        if env_file.exists():
            load_dotenv(dotenv_path=env_file, override=True)

        # 加载本地覆盖配置（不提交到Git）
        local_file = Path('.') / f'.env.{self.env}.local'
        if local_file.exists():
            load_dotenv(dotenv_path=local_file, override=True)

    def get(self, key, default=None):
        """获取配置值"""
        return os.getenv(key, default)

# 使用示例
config = ConfigManager(env="development")
print(f"当前环境: {config.get('APP_ENV')}")
print(f"API Key: {config.get('OPENAI_API_KEY')[:10]}...")  # 只显示前10个字符

5. Key Rotation and Monitoring

For production environments, it is recommended to implement key rotation and monitoring:

# key_manager.py
import os
import time
from datetime import datetime, timedelta

class APIKeyManager:
    """API Key 管理器"""

    def __init__(self):
        self.keys = {}
        self.key_history = []
        self.load_keys()

    def load_keys(self):
        """加载 API Keys"""
        # 可以从环境变量、数据库或密钥管理服务加载
        self.keys = {
            "openai": {
                "current": os.getenv("OPENAI_API_KEY"),
                "previous": os.getenv("OPENAI_API_KEY_PREVIOUS"),
                "created_at": datetime.now(),
                "rotation_days": 30  # 30天轮换一次
            },
            "anthropic": {
                "current": os.getenv("ANTHROPIC_API_KEY"),
                "previous": None,
                "created_at": datetime.now(),
                "rotation_days": 30
            }
        }

    def get_key(self, service):
        """获取当前可用的 Key"""
        key_info = self.keys.get(service)
        if not key_info:
            raise ValueError(f"未配置服务 {service} 的 API Key")

        # 检查是否需要轮换
        if self.should_rotate(key_info):
            self.rotate_key(service)

        return key_info["current"]

    def should_rotate(self, key_info):
        """检查是否需要轮换 Key"""
        rotation_days = key_info.get("rotation_days", 30)
        created_at = key_info.get("created_at", datetime.now())

        age = datetime.now() - created_at
        return age.days >= rotation_days

    def rotate_key(self, service):
        """轮换 API Key"""
        # 在实际应用中，这里会从密钥管理服务获取新 Key
        print(f"轮换 {service} 的 API Key...")

        key_info = self.keys[service]
        key_info["previous"] = key_info["current"]
        # 这里应该从安全的地方获取新 Key
        # key_info["current"] = get_new_key_from_vault(service)
        key_info["created_at"] = datetime.now()

        # 记录历史
        self.key_history.append({
            "service": service,
            "rotated_at": datetime.now(),
            "old_key": key_info["previous"][:10] + "..." if key_info["previous"] else None
        })

# 使用示例
key_manager = APIKeyManager()
openai_key = key_manager.get_key("openai")
print(f"OpenAI Key: {openai_key[:10]}...")

Recommended Development Tools

Choosing the right development tools can greatly improve development efficiency. Below are some recommended development tools.

1. Code Editor/IDE

Visual Studio Code (recommended)

Download URL：https://code.visualstudio.com/

Recommended extensions：

• Python: Python language support
• Pylance: Advanced Python language server
• Jupyter: Jupyter notebook support
• GitLens: Git enhancements
• Prettier: Code formatting
• Code Spell Checker: Spell checking
• Rainbow CSV: CSV file highlighting
• Thunder Client: API testing tool

VS Code configuration（.vscode/settings.json）：

{
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": false,
    "python.linting.flake8Enabled": true,
    "python.formatting.provider": "black",
    "python.formatting.blackArgs": [
        "--line-length",
        "88"
    ],
    "python.testing.pytestEnabled": true,
    "[python]": {
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.organizeImports": "always"
        }
    },
    "files.exclude": {
        "**/__pycache__": true,
        "**/.pytest_cache": true,
        "**/.venv": true,
        "**/venv": true
    }
}

PyCharm (Professional Edition)

Download URL：https://www.jetbrains.com/pycharm/

Features：

• Professional Python IDE
• Powerful debugging features
• Database tool integration
• Scientific computing support

2. Version Control: Git

Git is an essential version control tool.

Basic configuration：

# 配置用户信息
git config --global user.name "你的姓名"
git config --global user.email "你的邮箱"

# 配置默认编辑器（可选）
git config --global core.editor "code --wait"

# 创建 Git 仓库
cd ai-agent-project
git init

# 添加所有文件
git add .

# 提交
git commit -m "初始提交：AI Agent 项目"

# 连接到远程仓库（如 GitHub）
git remote add origin https://github.com/你的用户名/ai-agent-project.git
git branch -M main
git push -u origin main

3. Debugging Tools

Python debugger (pdb)

# 在代码中插入断点
import pdb

def complex_function(x):
    pdb.set_trace()  # 这里会进入调试器
    result = x * 2
    return result

# 常用 pdb 命令：
# n(ext) - 执行下一行
# s(tep) - 进入函数
# c(ontinue) - 继续执行
# l(ist) - 显示代码
# p(rint) - 打印变量值
# q(uit) - 退出调试器

VS Code debugging configuration

.vscode/launch.json：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 当前文件",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": true,
            "envFile": "${workspaceFolder}/.env"
        },
        {
            "name": "Python: 测试",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/tests",
            "console": "integratedTerminal",
            "justMyCode": true,
            "envFile": "${workspaceFolder}/.env"
        }
    ]
}

4. Testing Tools

pytest

# tests/test_agent.py
import pytest
from src.agents.base_agent import BaseAgent

def test_agent_initialization():
    """测试 Agent 初始化"""
    agent = BaseAgent(name="测试Agent")
    assert agent.name == "测试Agent"
    assert agent.messages == []

def test_agent_add_message():
    """测试添加消息"""
    agent = BaseAgent()
    agent.add_message("user", "你好")

    assert len(agent.messages) == 1
    assert agent.messages[0]["role"] == "user"
    assert agent.messages[0]["content"] == "你好"

Run tests:

# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_agent.py

# 运行特定测试函数
pytest tests/test_agent.py::test_agent_initialization

# 显示详细输出
pytest -v

# 显示覆盖率报告
pytest --cov=src

5. Code Quality and Formatting

black (code formatting)

# 格式化所有 Python 文件
black .

# 检查哪些文件需要格式化
black --check .

# 格式化单个文件
black src/agents/base_agent.py

flake8 (code checking)

# 检查代码质量
flake8 src/

# 忽略特定错误
flake8 --ignore=E501,W503 src/

# 显示错误统计
flake8 --statistics src/

pre-commit (Git hooks)

Create.pre-commit-config.yaml：

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black

  - repo: https://github.com/pycqa/flake8
    rev: 6.1.0
    hooks:
      - id: flake8
        args: [--max-line-length=88]

Install pre-commit:

pip install pre-commit
pre-commit install

6. Documentation Tools

Jupyter Notebook

For experiments and documentation:

# 启动 Jupyter
jupyter notebook

# 或使用 JupyterLab
jupyter lab

MkDocs (documentation generation)

Createdocs/directory andmkdocs.yml：

site_name: AI Agent 项目文档
site_url: https://your-project.com
nav:
  - 首页: index.md
  - API文档: api.md
  - 使用指南: guide.md
theme: readthedocs

Generate documentation:

# 安装 MkDocs
pip install mkdocs mkdocs-material

# 本地预览
mkdocs serve

# 构建文档
mkdocs build

7. Containerization Tools (Optional)

Docker

Dockerfile：

FROM python:3.9-slim

WORKDIR /app

# 复制依赖文件
COPY requirements.txt .

# 安装依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY src/ ./src/
COPY .env.example .env

# 设置环境变量
ENV PYTHONPATH=/app

# 运行应用
CMD ["python", "src/main.py"]

docker-compose.yml：

version: '3.8'

services:
  ai-agent:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs

8. Monitoring and Logging

loguru (logging library)

from loguru import logger
import sys

# 配置日志
logger.remove()  # 移除默认处理器
logger.add(
    sys.stderr,
    format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
    level="INFO"
)

logger.add(
    "logs/app_{time}.log",
    rotation="500 MB",  # 每500MB轮转
    retention="30 days",  # 保留30天
    compression="zip",  # 压缩旧日志
    level="DEBUG"
)

# 使用日志
logger.info("应用启动")
logger.debug(f"配置加载: {config}")
logger.error("API调用失败", exc_info=True)