📚 课程目录第4章环境搭建与SDK配置

4. 环境搭建与 SDK 配置

环境配置是所有 Agent 工具调用的起点。本节将依次完成 Python 与 Node.js 双语言运行时准备、核心依赖安装、API Key 获取与安全注入，并最终验证 SDK 能否正常通信。

4.1 运行环境版本要求

以下版本经社区与官方验证为稳定基线，低于基线版本可能出现协议不兼容或证书错误。

运行时	最低版本	推荐版本	验证命令
Python	3.9	3.11 / 3.12	`python --version`
Node.js	18 LTS	20 LTS / 22 LTS	`node --version`
npm	9	10 / 11	`npm --version`

版本兼容提示：Node.js 16 已于 2023 年 9 月终止维护，其 HTTP/2 实现存在多个安全漏洞，不应在生产环境中直接用于 Agent SDK 通信。

4.2 虚拟环境与项目初始化

Python 虚拟环境

python -m venv agent_env
source agent_env/bin/activate        # Linux / macOS
agent_env\Scripts\activate           # Windows PowerShell

Node.js 项目初始化

mkdir agent-tool-calling && cd agent-tool-calling
npm init -y

4.3 安装核心 SDK 依赖

依赖安装清单按语言拆分，两个运行时并非二选一，可根据项目需要分别部署或共存使用。

输入物：已激活的 Python 虚拟环境 / 已初始化的 Node.js 项目目录。

Python SDK 依赖

pip install openai==1.55.0
pip install pydantic==2.10.4
pip install httpx==0.28.1

Node.js SDK 依赖

npm install openai@^4.77.0
npm install zod@^3.24.1

安装检查：执行 pip freeze | grep openai（Python）或 npm list openai（Node.js）确认版本号与预期一致。版本不对时，使用 pip install --force-reinstall openai==1.55.0 或 npm install openai@4.77.0 --save-exact 锁定版本。

4.4 API Key 获取与安全配置

所有主流 Agent 平台（OpenAI、Anthropic、Google Gemini 等）均使用 Bearer Token 鉴权。下面的流程以 OpenAI 为例，其他平台仅在 Endpoint URL 与 Key 前缀上存在差异。

登录 platform.openai.com/api-keys，点击「Create new secret key」。
复制生成的 sk-... 密钥到剪贴板。
在项目根目录创建 .env 文件，写入密钥：

# .env  —— 禁止提交到版本控制
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.openai.com/v1
# 如果使用代理或中转服务，修改 BASE_URL 即可

# .gitignore 中必须包含 .env，防止密钥泄露
echo ".env" >> .gitignore

密钥泄露应急：一旦发现密钥被意外提交到 GitHub 等公开仓库，立即在平台侧吊销该密钥并创建新 Key。在 Git 历史中清除已提交密钥的最佳方式使用 git filter-branch 或 GitHub 官方秘密扫描工具。

4.5 SDK 初始化与连通性测试

编写一段最小化测试代码，覆盖：加载环境变量 → 创建 Client → 发送请求 → 解析响应四个环节。

Python 连通测试

# test_connect.py
import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL")
)

# 调用模型列表 API 验证连通性
models = client.models.list()
print(f"连接成功，可用模型数: {len(models.data)}")
print([m.id for m in models.data[:5]])

# 运行
python test_connect.py

Node.js 连通测试

// test_connect.mjs
import OpenAI from 'openai';
import 'dotenv/config';

const client = new OpenAI({
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: process.env.OPENAI_BASE_URL,
});

const models = await client.models.list();
console.log(`连接成功，可用模型数: ${models.data.length}`);
console.log(models.data.slice(0, 5).map(m => m.id));

# 运行
node test_connect.mjs

输出物：终端打印可用模型列表，例如 ['gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', ...]。若输出为空或报错，参见下方常见错误表。

4.6 常见配置错误与排查

错误现象	根因	解决步骤
`401 Unauthorized`	API Key 无效、过期或环境中未正确加载	检查 .env 是否存在、Key 是否被引号包裹、平台侧是否被吊销
`404 Not Found`	BASE_URL 地址错误或模型 ID 不存在	确认 `OPENAI_BASE_URL` 末尾是否包含 `/v1`；换用 `gpt-4o-mini` 测试
`SSL: CERTIFICATE_VERIFY_FAILED`	Python 证书验证失败（常见于自签名代理）	设置 `SSL_CERT_FILE` 环境变量，或临时使用 `verify=False`（仅限开发）
`ModuleNotFoundError: No module named 'openai'`	虚拟环境未激活或依赖未安装	执行 `pip list` 确认；激活正确环境；重新 `pip install openai`
`ERR_REQUIRE_ESM`	Node.js 测试文件使用 CommonJS 但 SDK 为 ESM 包	将文件后缀改为 `.mjs`；或在 `package.json` 添加 `"type": "module"`

4.7 稳定版配置检查表

完成以下所有项目后，即可认为环境就绪，后续章节可直接使用此基底。

Python 3.9+ / Node.js 18+ 已安装并加入 PATH
虚拟环境（Python venv）已激活，且 shell 提示符前显示环境名
openai / pydantic / dotenv 等依赖已安装并锁定版本
.env 文件存在且包含正确的 API Key，.gitignore 已排除该文件
连通性测试脚本返回模型列表，无 401/404 错误
SDK Client 能正常发起 streaming / non-streaming 请求（可选进一步验证）