1.5 快速入门：环境配置与第一个应用

1.5 快速入门：环境配置与第一个多智能体应用

一句行话开头：环境对了，后面的坑就少一半。这一节我们不做虚的，直接把环境配好、把第一个会对话的多智能体应用跑起来。你跟着敲，遇到报错知道去哪查。

第一步：装包与隔离环境

我们强烈建议用虚拟环境，别把框架直接装进系统 Python——版本冲突会让你后面怀疑人生。框架主包通过 pip 安装，社区扩展按需加。

# 创建并激活虚拟环境（示例命令，按你的系统习惯执行）
python -m venv autogen-env
source autogen-env/bin/activate   # Windows 用 autogen-env\Scripts\activate
pip install pyautogen             # 经典 API 包名
​

装完验证一下导入不报错：

# 验证安装：能导入即说明包就绪
from autogen import ConversableAgent, AssistantAgent, UserProxyAgent
print("AutoGen 就绪")   # 预期输出：AutoGen 就绪
​

如果你看到版本号相关的警告，一般无伤大雅；如果是 ImportError，先确认虚拟环境已激活、pip 装到了正确的解释器。

第二步：准备模型凭据

AutoGen 本身不提供模型，它对接你已有的大模型服务。凭据通过配置字典传入，而不是写死在代码里——我们用环境变量读，避免密钥进版本库。

# 从环境变量读凭据，绝不硬编码进源码
import os
from autogen import ConversableAgent

llm_cfg = {
    "model": "gpt-4o-mini",
    "api_key": os.environ.get("OPENAI_API_KEY"),  # 提前在终端 export
    "temperature": 0.2,   # 偏低，减少胡说
}
print("key loaded:", bool(llm_cfg["api_key"]))   # 预期 True
​

第三步：跑通第一个双 Agent 对话

下面这个例子是一个"规划者"和一个"执行者"。规划者只出步骤，执行者只回执。我们用最小代码看消息怎么往返。

from autogen import ConversableAgent
import os

cfg = {"model": "gpt-4o-mini", "api_key": os.environ.get("OPENAI_API_KEY")}

planner = ConversableAgent(
    "planner", llm_config=cfg,
    system_message="你只输出操作步骤，不写代码。",
)
executor = ConversableAgent(
    "executor", llm_config=cfg,
    system_message="你确认步骤合理，并说准备执行。",
)

chat = planner.initiate_chat(executor, message="目标：统计文件夹里有多少 txt。", max_turns=2)
print(chat.summary)
​

预期你会看到一段两轮的对话：planner 列出步骤，executor 确认。这就证明"对话即编排"的回路通了。注意 max_turns=2 限制了往返次数，避免模型聊起来没完。

常见报错与对策

• AuthenticationError：键值没读到，确认环境变量名和代码里一致。
• RateLimitError：短时间调用太多，加重试或降低并发。
• 递归深度报错：通常是两个 Agent 互相同步发消息没设上限，检查 max_turns。

跑通之后，下一步做什么

第一个双 Agent 跑通，只是证明了"对话即编排"的回路是通的。接下来建议你做一个最小验收清单，确认环境真的稳：第一，导入无报错且能打印版本；第二，凭据通过环境变量读入、bool 检查为 True；第三，一次完整对话能结束并打印 summary，而不是卡在等输入；第四，故意把 max_turns 设成 1，确认对话会如期停下——这步是在提前验证你后面做群聊时最易翻车的终止逻辑。四项都过，你的环境才算"可用于学习后续章节"。

然后别急着上复杂系统。我们建议下一步做一个"三 Agent 流水线"练手：规划者出步骤、执行者回执、复核者挑刺，手动用 initiate_chat 串起来（GroupChat 到第四章才讲）。它比双 Agent 只多一个角色，却能让你直观体会"加角色比改流程简单"——这正是框架的扩展优势第一次落在你手上。如果这一步都跑不顺，先别进第二章，回头把本节的报错对策逐项排查，环境不稳后面每章都会反复踩。

环境验收清单

• 虚拟环境已激活，pip 装到了正确的解释器。
• from autogen import ... 无 ImportError。
• 凭据走环境变量，仓库内源码不含明文 key。
• 对话能在 max_turns 内结束，summary 可打印。

让环境可复制：给队友一份就能跑

第一个应用跑通后，这份环境应该能原样交给同事或部署机器，而不是"只有你电脑能跑"。三个动作让它可复制：第一，把依赖写进 requirements 文件并锁版本，别人 pip install -r 就能拿到一致的包，而不是各自装最新版撞兼容坑；第二，把环境变量的"名字清单"写进一份示例配置（如 .env.example），只列键不填值，同事照着填自己的 key 即可，密钥本身永不进仓库；第三，把跑通双 Agent 的命令写成一个 run_demo.py，新人一条命令就能复现你刚才验证的回路。

可复制性看起来是"工程整洁"的小事，实则决定了你后面能不能顺畅做团队协作和部署（第六章）。很多项目卡在"在我机器上能跑"，根因就是第一步没把环境和凭据规范化。第一章的入门看似简单，但养成的"环境即代码"习惯，会一直护着你到生产。

本节要点回顾

• 用虚拟环境装包，凭据走环境变量不硬编码。
• initiate_chat 开启对话，max_turns 控制往返。
• 跑通双 Agent 即证明回路通，后面章节都是加料。
• 用四项验收清单确认环境可用，再做三 Agent 流水线练手。
• 用依赖锁版本、示例配置、可跑脚本让环境可复制。

⚠️ 千万别把 API key 写进会提交到仓库的源码，泄露后账单和权限都危险。

💡 第一个应用的价值不在功能，而在验证"对话即编排"的回路——后面所有复杂系统都长这样。