模块2: 环境搭建与API配置

在构建AI智能体之前，你需要一个正确配置的开发环境。本模块将带你完成每一步——从安装Python到验证你的第一个API连接。完成后，你将拥有一个可用于本教程系列其余部分的项目脚手架。

开始之前，你需要准备以下内容：

• Python 3.10+ — 我们推荐Python 3.11或3.12，以获得与现代AI库的最佳兼容性
• OpenAI API密钥 — 从 platform.openai.com 获取
• Anthropic API密钥 — 从 console.anthropic.com 获取
• 代码编辑器 — 推荐VS Code，因其出色的Python支持和集成终端
• 基本Python知识 — 函数、类、字典，以及包管理
• 终端/命令行 — 你应该能熟练运行命令

检查Python版本

打开终端并验证你的Python安装：

# Check Python version (must be 3.10 or higher)
python --version
# Output: Python 3.12.4

# On some systems, you may need to use python3
python3 --version

如果你没有安装Python，请从 python.org 下载。在macOS上也可以使用 brew install python。在Ubuntu/Debian上使用 sudo apt install python3。

我们强烈建议使用虚拟环境来隔离项目依赖。这可以防止你机器上不同Python项目之间的版本冲突。

创建虚拟环境

# Create project directory
mkdir ai-agent-tutorial
cd ai-agent-tutorial

# Create a virtual environment
python -m venv venv

# Activate it (macOS / Linux)
source venv/bin/activate

# Activate it (Windows)
venv\Scripts\activate

# You should see (venv) in your terminal prompt

安装所需的包

# Install all dependencies at once
pip install openai anthropic python-dotenv

# Verify installation
pip list | grep -E "openai|anthropic|dotenv"

这将安装三个包：

一个良好的项目结构将在智能体变得复杂时为你节省很多麻烦。以下是我们在本教程系列中将构建的结构：

ai-agent-tutorial/
├── .env                 # API keys (NEVER commit this file!)
├── .gitignore           # Must include .env
├── requirements.txt     # Pinned dependencies
├── config.py            # Centralised configuration
├── agent_openai.py      # OpenAI-based agent implementation
├── agent_anthropic.py   # Anthropic-based agent implementation
├── tools.py             # Tool definitions and implementations
├── memory.py            # Memory management (short + long term)
├── evaluator.py         # Agent evaluation and testing
└── main.py              # Entry point

每个文件都有明确的职责。这种关注点分离使得交换组件变得容易——例如，只需更改一个import即可从OpenAI切换到Anthropic。

创建.gitignore文件

如果你使用Git（你应该使用），请立即创建 .gitignore 以防止意外提交敏感文件：

# .gitignore
.env
venv/
__pycache__/
*.pyc
.DS_Store

API密钥是OpenAI和Anthropic识别和计费你的账户的方式。它们是机密信息，绝不能出现在你的源代码、提交历史或公共仓库中。

获取API密钥

OpenAI：前往 platform.openai.com/api-keys，点击"Create new secret key"，命名后复制密钥。你只能看到一次。

Anthropic：前往 console.anthropic.com/settings/keys，点击"Create Key"，命名后复制。同样的规则——你只能看到一次。

在.env文件中存储密钥

在项目根目录创建一个 .env 文件。该文件在运行时加载，但绝不提交到版本控制：

# .env
OPENAI_API_KEY=sk-proj-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here

替代方案：系统环境变量

对于生产部署，你可能更倾向于将密钥设置为系统环境变量，而不是使用 .env 文件：

# macOS / Linux (add to ~/.bashrc or ~/.zshrc for persistence)
export OPENAI_API_KEY="sk-proj-your-key-here"
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Windows PowerShell
$env:OPENAI_API_KEY="sk-proj-your-key-here"
$env:ANTHROPIC_API_KEY="sk-ant-your-key-here"

现在让我们编写一个配置模块来加载和验证你的API密钥。这个模式确保你能在任何API调用之前尽早发现缺失的密钥。

基本密钥加载

# config.py
import os
from dotenv import load_dotenv

# Load variables from .env file into environment
load_dotenv()

# Read keys from environment
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")

# Validate - fail fast if keys are missing
assert OPENAI_API_KEY, "Missing OPENAI_API_KEY in .env file"
assert ANTHROPIC_API_KEY, "Missing ANTHROPIC_API_KEY in .env file"

print("API keys loaded successfully.")

验证连接

在进入下一模块之前，让我们通过向每个供应商发起最小API调用来验证密钥是否有效：

# verify_setup.py
import os
from dotenv import load_dotenv
from openai import OpenAI
import anthropic

load_dotenv()

# --- Test OpenAI ---
print("Testing OpenAI connection...")
oai_client = OpenAI()  # Automatically reads OPENAI_API_KEY
response = oai_client.chat.completions.create(
    model="gpt-4o-mini",   # Use the cheapest model for testing
    messages=[{"role": "user", "content": "Say 'hello' and nothing else."}],
    max_tokens=10
)
print(f"  OpenAI response: {response.choices[0].message.content}")

# --- Test Anthropic ---
print("Testing Anthropic connection...")
ant_client = anthropic.Anthropic()  # Automatically reads ANTHROPIC_API_KEY
message = ant_client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=10,
    messages=[{"role": "user", "content": "Say 'hello' and nothing else."}]
)
print(f"  Anthropic response: {message.content[0].text}")

print("\nAll connections verified! Your environment is ready.")

运行此文件：

python verify_setup.py
# Expected output:
# Testing OpenAI connection...
#   OpenAI response: hello
# Testing Anthropic connection...
#   Anthropic response: hello
# All connections verified! Your environment is ready.

常见错误排查

健壮的配置模块

对于生产级别的配置，使用一个配置类来处理多个环境（开发、测试、生产）并提供合理的默认值：

# config.py - production-quality configuration
import os
from dataclasses import dataclass
from dotenv import load_dotenv

load_dotenv()

@dataclass
class Config:
    """Centralised configuration for the AI agent project."""
    openai_api_key: str = ""
    anthropic_api_key: str = ""
    default_provider: str = "anthropic"  # or "openai"
    default_model: str = "claude-sonnet-4-20250514"
    max_tokens: int = 1024
    temperature: float = 0.0
    max_agent_steps: int = 10
    log_file: str = "agent_log.jsonl"

    @classmethod
    def from_env(cls) -> "Config":
        """Load configuration from environment variables."""
        return cls(
            openai_api_key=os.getenv("OPENAI_API_KEY", ""),
            anthropic_api_key=os.getenv("ANTHROPIC_API_KEY", ""),
            default_provider=os.getenv("DEFAULT_PROVIDER", "anthropic"),
            max_agent_steps=int(os.getenv("MAX_AGENT_STEPS", "10")),
        )

    def validate(self) -> list[str]:
        """Return a list of configuration errors (empty = all good)."""
        errors = []
        if not self.openai_api_key:
            errors.append("OPENAI_API_KEY is not set")
        if not self.anthropic_api_key:
            errors.append("ANTHROPIC_API_KEY is not set")
        return errors

# Usage
config = Config.from_env()
errors = config.validate()
if errors:
    print("Configuration errors:")
    for e in errors:
        print(f"  - {e}")
else:
    print("Configuration OK")

VS Code推荐扩展

如果你使用VS Code，安装以下扩展以获得AI智能体项目的最佳开发体验：