3.1 环境搭建与项目初始化

3.1 环境搭建与项目初始化

在体系中的位置：第二章把零件讲完了，第三章动手。3.1 是动手的第一步——把环境装对、骨架立住，后面所有代码才有地方跑。踩坑十有八九出在环境，不在代码。

一个数字先说：AgentScope 2.0 要求 Python 3.9+。低于这个版本，部分异步语法和类型注解会直接报语法错，别在 3.8 上浪费时间。

为什么用虚拟环境：不是洁癖是 necessity

依赖冲突是多智能体项目的头号杀手。AgentScope 依赖特定的 pydantic、httpx 版本，和你机器上别的项目可能打架。虚拟环境把依赖锁在隔离空间，避免"装了 A 崩了 B"。

用 Python 内置 venv 即可，无需额外工具：

# 创建隔离环境
python -m venv .venv

# 激活（Linux / macOS）
source .venv/bin/activate
# 激活（Windows）
.venv\Scripts\activate

# 安装 AgentScope 主线
pip install agentscope

# 如需可视化调试，装 studio 组件
pip install "agentscope[studio]"
​

运行说明：激活后命令行前缀会出现 (.venv)，表示已在隔离环境。之后 pip install 的包只进这个环境。装完用 python -c "import agentscope; print(agentscope.__version__)" 验证能导入且版本符合预期。

配置模型：密钥不落代码

AgentScope 调用模型需要 API Key。把密钥写死在代码里，一旦提交到仓库就泄露。正确做法是走环境变量。

import os
from agentscope.models import OpenAIChatModel

# 从环境变量读取，代码里绝不出现明文密钥
model = OpenAIChatModel(
    model_name="gpt-4o-mini",
    api_key=os.environ["OPENAI_API_KEY"],  # 终端里 export OPENAI_API_KEY=xxx
)

# model = DashScopeChatModel(model_name="qwen-max", api_key=os.environ["DASHSCOPE_API_KEY"])
​

运行说明：终端执行 export OPENAI_API_KEY=你的钥匙 后再跑脚本。若变量未设置，os.environ[...] 会抛 KeyError，这正是我们要的——宁可启动即失败，也不要带着空钥匙静默跑。

项目骨架：目录怎么摆

多智能体项目容易长成意大利面。推荐一个清晰的分层骨架，把"定义"和"编排"分开：

my_agentscope_app/
├── .venv/                # 隔离环境（不入库）
├── agents/               # 智能体定义
│   ├── planner.py
│   └── coder.py
├── tools/                # 工具定义
│   └── weather.py
├── envs/                 # 自定义环境
│   └── board.py
├── configs/              # 模型与运行配置
│   └── model_config.py
├── main.py               # 编排入口
└── requirements.txt      # 依赖清单
​

这种摆法的好处：智能体、工具、环境各归其位，编排逻辑集中在 main.py，改一个角色不影响其他。下面给一个最小 main.py 骨架。

# main.py —— 编排入口
import asyncio
from agentscope.agents import DialogAgent
from agentscope.msghub import MsgHub
from configs.model_config import build_model

async def main():
    model = build_model()  # 从 configs 统一构建模型
    planner = DialogAgent(name="规划者", sys_prompt="拆解任务。", model=model)
    coder = DialogAgent(name="执行者", sys_prompt="按步骤实现。", model=model)
    async with MsgHub([planner, coder],
                      announcement=Msg("user", "写一个快速排序", "user")) as hub:
        await planner()
        await coder()

if __name__ == "__main__":
    asyncio.run(main())
​

运行输出（典型）：规划者先输出步骤，执行者输出代码。骨架跑通，说明环境、模型、消息中枢三件基础都已就位。

案例：一次典型的"装好却跑不通"

背景：新手按文档装完，跑 demo 报 ModuleNotFoundError: agentscope.msghub。

操作（排查）：先看是否激活了正确 venv（which python 指向 .venv 内）；再看装的版本——旧 1.x 没有 msghub 模块，2.0 才有。

结果：发现 pip 装的是 1.x 老包。重装 pip install -U agentscope 解决。

解读：这类问题九成是"装错版本"或"跑错环境"。版本对齐是 AgentScope 入门第一道关。

变式：若公司内网无法直连 PyPI，用私有镜像源 pip install -i https://你的镜像/simple agentscope，但务必校验包哈希，避免供应链投毒。

本节要点回顾

• Python 3.9+ 是硬门槛，别在更低版本折腾。
• 虚拟环境不是洁癖，是避免依赖冲突的必需。
• 密钥走环境变量，代码里只 os.environ[...]，宁可启动失败也不要空钥匙静默跑。
• 项目骨架把 agents/tools/envs/configs/main 分开，编排集中在 main，易维护。

⚠️ 装完务必核对版本：msghub 是 2.0 才有。报 ModuleNotFoundError: agentscope.msghub 多半是装了 1.x，升到 2.0 主线再试。

💡 初始化项目第一件事不是写智能体，而是 python -c "import agentscope; print(agentscope.__version__)"。版本不对，后面全白写。