开发Agent之前的环境准备——小白也能看懂的保姆级教程

前言

上一篇文章《如何开发一个Agent》介绍了Agent开发的完整流程和实战案例，很多朋友反馈：道理我都懂，但到了自己动手的时候，连第一步都不知道怎么迈。

别急，这篇文章就是专门解决这个问题的。我会从零开始，手把手带你完成开发Agent所需的所有环境准备，每一步都有详细说明，确保你跟着操作就能搞定。

一、整体准备流程

在正式开发Agent之前，你需要完成以下准备工作：

image.png

下面我们逐步操作。

二、安装Python

为什么需要Python？

目前主流的Agent开发框架（LangChain、CrewAI、AutoGen等）几乎都是用Python写的。所以Python是必装的。

就好比你要做中餐，首先得有一口锅。Python就是那口锅。

安装步骤（Windows系统）

1. 下载Python安装包

打开浏览器，访问Python官网：

https://www.python.org/downloads/

点击页面上醒目的黄色按钮"Download Python 3.x.x"，下载最新版本即可。

2. 运行安装程序

双击下载好的安装文件，你会看到安装界面。这里有一个非常重要的操作：

务必勾选底部的"Add Python to PATH"，这个选项会让你在任何地方都能使用Python命令。如果忘了勾选，后面会遇到各种"找不到命令"的问题。

勾选后，点击"Install Now"即可。

3. 验证安装是否成功

安装完成后，打开命令行：

• 按下键盘的 Win + R 键
• 输入 cmd，回车

在弹出的黑色窗口中输入：

python --version

如果显示类似 Python 3.12.x 的版本号，说明安装成功了。

安装步骤（Mac系统）

Mac用户可以直接从Python官网下载Mac版安装包：

1. 访问 https://www.python.org/downloads/
2. 下载Mac版 .pkg 安装文件
3. 双击运行，按提示完成安装

安装完成后，打开"终端"应用，输入 python3 --version 验证。

三、安装代码编辑器

为什么需要编辑器？

写代码需要一个专门的工具，就像写文档用Word一样。虽然用记事本也能写代码，但专业编辑器能帮你高亮代码、自动补全、检查错误，效率高很多。

推荐：VS Code

VS Code是微软出品的免费编辑器，全球开发者使用最多，中文支持非常好。

安装步骤：

1. 打开浏览器，访问：https://code.visualstudio.com/
2. 点击页面上的"Download"按钮下载
3. 双击安装文件，一路"下一步"即可
4. 安装完成后打开VS Code

必装插件（让VS Code更好用）：

打开VS Code后，点击左侧的扩展图标（四个小方块的图标），搜索并安装以下插件：

安装完成后重启VS Code，界面就变成中文了。

四、创建虚拟环境

什么是虚拟环境？

这是很多小白容易忽略但非常重要的一步。

打个比方：虚拟环境就像是给你的项目一个独立的"房间"。每个房间里可以放不同的东西（依赖包），互不干扰。如果所有项目都共用一套环境，很容易出现A项目需要包的1.0版本，B项目需要2.0版本，结果互相冲突的问题。

创建步骤

1. 创建项目文件夹

在你希望的位置创建一个文件夹，比如 my-agent（名字随意），用来存放你的项目代码。

2. 打开命令行，进入项目文件夹

# Windows
cd D:\projects\my-agent

# Mac
cd ~/projects/my-agent

3. 创建虚拟环境

python -m venv .venv

这条命令会在当前文件夹下创建一个名为 .venv 的隐藏文件夹，里面就是你的独立环境。

4. 激活虚拟环境

# Windows (PowerShell)
.\.venv\Scripts\Activate

# Windows (cmd)
.\.venv\Scripts\activate.bat

# Mac / Linux
source .venv/bin/activate

激活成功后，你会看到命令行前面多了一个 (.venv) 的标记，说明你已经进入了虚拟环境。

小贴士：每次打开新的命令行窗口，都需要重新激活虚拟环境。忘记激活就安装包的话，包会装到全局环境里，项目可能找不到。

在VS Code中使用虚拟环境

1. 用VS Code打开你的项目文件夹（文件 → 打开文件夹）
2. 按 Ctrl + Shift + P（Mac按 Cmd + Shift + P）打开命令面板
3. 输入 Python: Select Interpreter，回车
4. 选择带有 .venv 路径的那个Python解释器

这样VS Code的终端和代码运行都会自动使用虚拟环境。

五、获取大模型API Key

API Key是什么？

API Key就是一把"钥匙"，让你的程序有权限调用大模型的能力。没有这把钥匙，你的代码就无法和大模型对话。

类比一下：大模型就像一个很聪明的专家，但他在一间上锁的办公室里。API Key就是那把钥匙，你拿到钥匙才能进去请教他。

推荐方案：DeepSeek（国内首选）

DeepSeek是国内的大模型，注册简单、有免费额度、中文效果好，非常适合入门。

获取步骤：

1. 打开 https://platform.deepseek.com/
2. 点击右上角"注册"，用手机号注册账号
3. 注册完成后登录，进入控制台
4. 在左侧菜单找到"API Keys"
5. 点击"创建API Key"，给它取个名字（比如"my-agent"）
6. 复制生成的Key

重要提醒：API Key只在创建时显示一次，请立即复制并保存到安全的地方（比如记事本）。如果丢了就只能重新创建。

其他可选方案

以上平台都是国内平台，注册简单，新手建议从DeepSeek或智谱AI开始。

安全存放API Key

拿到Key后，千万不要直接写在代码里。推荐使用环境变量文件的方式：

在项目文件夹下创建一个 .env 文件，内容如下：

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx

然后在代码中通过 python-dotenv 库读取：

from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("DEEPSEEK_API_KEY")

为什么不能直接写在代码里？ 如果你的代码分享给他人或上传到代码托管平台，API Key会被所有人看到，别人就能用你的Key来消耗你的额度，甚至产生费用。

六、安装开发框架

配置pip国内下载源

在安装任何包之前，强烈建议先配置国内的pip下载源，否则下载速度会很慢甚至失败。

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

这条命令会把默认下载源切换到清华大学镜像，国内下载速度飞快。

安装LangChain（推荐框架）

确保虚拟环境已激活（命令行前面有 (.venv) 标记），然后执行：

pip install langchain langchain-openai python-dotenv

这条命令会安装：

• langchain：Agent开发核心框架
• langchain-openai：连接大模型的工具（也兼容DeepSeek等API）
• python-dotenv：读取环境变量文件的工具

等待安装完成即可，过程中会自动下载很多依赖包，这是正常的。

如果你选择其他框架

# CrewAI
pip install crewai

# AutoGen
pip install autogen-agentchat

七、验证环境

所有安装完成后，我们跑一段代码来验证环境是否正常。

验证流程

image.png

测试代码

在项目文件夹中创建 test_env.py 文件，粘贴以下代码：

import sys
print("=" * 50)
print("Agent开发环境检测")
print("=" * 50)

# 检查Python版本
print(f"\n1. Python版本: {sys.version}")
if sys.version_info >= (3, 9):
    print("   ✓ Python版本满足要求")
else:
    print("   ✗ 请升级到Python 3.9以上")
    sys.exit(1)

# 检查依赖包
print("\n2. 检查依赖包:")
try:
    import langchain
    print(f"   ✓ langchain 已安装")
except ImportError:
    print("   ✗ langchain 未安装，请执行: pip install langchain")

try:
    from langchain_openai import ChatOpenAI
    print(f"   ✓ langchain-openai 已安装")
except ImportError:
    print("   ✗ langchain-openai 未安装，请执行: pip install langchain-openai")

try:
    from dotenv import load_dotenv
    print(f"   ✓ python-dotenv 已安装")
except ImportError:
    print("   ✗ python-dotenv 未安装，请执行: pip install python-dotenv")

# 检查API Key
print("\n3. 检查API Key配置:")
try:
    from dotenv import load_dotenv
    import os
    load_dotenv()
    api_key = os.getenv("DEEPSEEK_API_KEY")
    if api_key:
        print(f"   ✓ DEEPSEEK_API_KEY 已配置 (前6位: {api_key[:6]}...)")
    else:
        print("   ✗ 未找到DEEPSEEK_API_KEY，请检查.env文件")
        sys.exit(0)
except Exception as e:
    print(f"   ✗ 读取配置出错: {e}")
    sys.exit(1)

# 测试大模型连接
print("\n4. 测试大模型连接:")
try:
    from langchain_openai import ChatOpenAI

    llm = ChatOpenAI(
        model="deepseek-chat",
        api_key=api_key,
        base_url="https://api.deepseek.com"
    )
    response = llm.invoke("请用一句话说：你好")
    print(f"   ✓ 大模型返回: {response.content}")
except Exception as e:
    print(f"   ✗ 连接失败: {e}")
    print("     请检查API Key是否正确，网络是否正常")

print("\n" + "=" * 50)
print("检测完成！如果全部显示 ✓，说明环境已就绪")
print("=" * 50)

运行测试：

python test_env.py

如果所有项目都显示 ✓，恭喜你，环境准备完成！

八、常见问题汇总

Q1："python"不是内部或外部命令

原因：安装Python时没有勾选"Add Python to PATH"。

解决办法：

1. 重新运行Python安装程序
2. 选择"Modify"
3. 勾选"Add Python to PATH"
4. 完成后重启命令行

Q2：pip install 下载特别慢或超时

原因：默认的pip源在国外，网络不稳定。

解决办法：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Q3：安装包时报红色错误

常见原因和对策：

• "Permission denied" → 使用管理员权限运行命令行
• "No matching distribution" → Python版本太低，升级Python
• "Microsoft Visual C++ required" → 安装Microsoft C++ Build Tools

Q4：VS Code终端显示"无法加载文件 Activate.ps1"

原因：PowerShell默认禁止运行脚本。

解决办法：
以管理员身份打开PowerShell，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Q5：API Key调用报错 "401 Unauthorized"

原因：API Key无效或已过期。

解决办法：

1. 登录对应平台检查Key是否存在
2. 确认Key没有多余的空格
3. 如果不确定，直接重新创建一个

九、环境准备检查清单

最后，给你一个检查清单，对照着逐项确认：

全部打勾后，你就可以正式开始Agent开发了！回到上一篇《如何开发一个Agent》，跟着实战案例动手吧。

结语

环境准备看起来步骤不少，但每一步都不难，跟着操作就行。最容易踩坑的三个地方是：

1. 安装Python时忘记勾选PATH —— 导致命令行找不到Python
2. 没有使用虚拟环境 —— 导致包冲突或找不到包
3. API Key保管不当 —— 直接写在代码里导致泄露

避开这三个坑，后面的开发就顺畅了。

如果你在操作过程中遇到任何问题，欢迎在评论区留言，我会一一解答。下一篇文章我们将进入实战环节，从零开发你的第一个Agent！