Appearance
安装与环境
AgentScope 2.x 要求 Python >=3.11。本页用 uv 在系统 Python 较旧的情况下也能锁定一个 可复现的 3.11+ 虚拟环境，再安装 agentscope 2.0.4 并配置模型凭证。
版本基线：本文以 PyPI 上的
agentscope 2.0.4（发布于 2026-07-07）为准，要求 Python>=3.11。1.x 与 2.x API 不兼容，不要混装。
前置：Python 版本与 uv
AgentScope 2.x 依赖 Python 3.11 及以上的语法与标准库。macOS 与多数 Linux 发行版自带的 系统 Python 可能仍是 3.9 或 3.10，直接用系统 Python 安装会失败。推荐使用 uv：它能在没有 3.11 的情况下自动下载并管理指定版本的解释器，且创建虚拟环境的速度远快于 venv。
如果你还不熟悉 uv，先阅读 Python 依赖管理 · uv。
安装 uv 本身（已安装可跳过）：
bash
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或通过 Homebrew
brew install uvpowershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"创建虚拟环境
用 uv 创建一个基于 Python 3.11 的虚拟环境：
bash
uv venv --python 3.11uv 会在当前目录生成 .venv。如果本机没有 3.11，uv 会自动下载对应版本，无需手动安装。
激活虚拟环境：
bash
source .venv/bin/activatepowershell
.venv\Scripts\Activate.ps1激活后 python 与 pip 都指向 .venv 内的解释器。后续命令默认在已激活环境中执行。
安装 AgentScope
在已激活的虚拟环境中安装稳定版：
bash
uv pip install agentscope如需锁版本以保证可复现，显式指定到当前基线：
bash
uv pip install 'agentscope==2.0.4'
uv pip install与pip install等价，但速度更快且自带依赖解析。如果你没有 uv，也可以 用pip install agentscope，但请确保当前 Python 已是 3.11+。
从源码安装
需要追踪 main 分支或贡献代码时，从 GitHub 克隆并以可编辑模式安装：
bash
git clone -b main https://github.com/agentscope-ai/agentscope.git
cd agentscope
uv pip install -e .可编辑模式下修改源码后无需重装即可立即生效。
可选依赖（extras）
agentscope 的核心安装只包含框架本体。RAG、Workspace 沙箱、Agent Service 后端、各模型集成 等能力以 extras 形式按需安装。macOS / Linux 下安装带 extras 的包时，方括号会被 shell 解释， 必须用引号包裹或转义：
bash
# 推荐：用单引号包裹
uv pip install 'agentscope[full]'
# 或转义方括号
uv pip install agentscope\[full\]| extras | 用途 | 何时安装 |
|---|---|---|
full | 一次性装入所有模型集成与工具依赖 | 想快速试通、不介意体积 |
models | 模型集成捆绑包 | 只需多家模型 API，不需要工具 / RAG / 服务后端 |
gemini | Google Gemini 集成 | 使用 Gemini 模型 |
ollama | Ollama 本地模型集成 | 使用本地 Ollama 服务 |
xai | xAI（Grok）集成 | 使用 xAI 模型 |
rag | RAG 检索增强依赖 | 使用 RAG 中间件 |
milvuslite | Milvus Lite 向量库 | RAG 使用 Milvus Lite 作为向量存储 |
workspace | Workspace 沙箱依赖 | 使用 Local / Docker / E2B 沙箱执行工具 |
tools | 工具相关依赖 | 使用内置工具或自定义工具的额外依赖 |
service | Agent Service FastAPI 后端 | 部署多租户 Agent Service |
storage | 持久化存储依赖 | 使用数据库 / 对象存储后端 |
s3 | S3 兼容存储 | Workspace 或存储使用 S3 |
mem0 | Mem0 长期记忆集成 | 使用 Mem0 记忆中间件 |
reme | ReMe 记忆集成 | 使用 ReMe 记忆中间件 |
dev | 开发与测试依赖 | 贡献源码、跑测试 |
可以组合多个 extras：
bash
uv pip install 'agentscope[rag,workspace,ollama]'模型凭证环境变量
AgentScope 通过环境变量读取各模型提供商的 API Key。不要把真实密钥写进代码、 把 .env 提交到 Git，或在教程里粘贴明文。 推荐用项目根目录的 .env 文件配合 python-dotenv 加载，或临时用 shell export。
.env 文件示例（只写变量名与占位符，不要填真实值）：
bash
# .env —— 必须加入 .gitignore，不要提交
DASHSCOPE_API_KEY=your_dashscope_key_here
OPENAI_API_KEY=your_openai_key_here
ANTHROPIC_API_KEY=your_anthropic_key_here在代码中通过 os.environ 读取，不在源码里硬编码：
python
import os
# 从环境变量读取，缺失时会抛 KeyError，避免静默使用空值
dashscope_key = os.environ["DASHSCOPE_API_KEY"]各提供商对应的环境变量与获取入口：
| 提供商 | 环境变量 | 获取入口 | 说明 |
|---|---|---|---|
| DashScope / 通义千问 | DASHSCOPE_API_KEY | 阿里云百炼控制台 | Qwen 系列模型 |
| OpenAI | OPENAI_API_KEY | platform.openai.com | GPT 系列模型 |
| Anthropic | ANTHROPIC_API_KEY | console.anthropic.com | Claude 系列模型 |
| Google Gemini | GEMINI_API_KEY 或 GOOGLE_API_KEY | ai.google.dev | Gemini 系列模型 |
| DeepSeek | DEEPSEEK_API_KEY | platform.deepseek.com | DeepSeek 模型 |
| Moonshot | MOONSHOT_API_KEY | platform.moonshot.cn | Kimi 系列模型 |
| xAI | XAI_API_KEY | x.ai | Grok 系列模型 |
| Ollama | 无需 API Key | 本地运行 ollama serve | 本地模型，无凭证 |
AgentScope 的 Agent 在使用工具调用（tool calling）时，所选模型必须原生支持 tool calling。部分小模型或量化模型可能不支持，调用时会报错。选用模型前先确认其 tool calling 支持情况。
验证安装
确认 AgentScope 已正确安装且版本符合预期：
bash
python -c "import agentscope; print(agentscope.__version__)"正常输出应显示 2.0.4（或你安装的版本号）。agentscope.__version__ 由包内的 _version 模块提供，是官方 __init__.py 中 __all__ 导出的公开属性，可以放心用于版本校验脚本。
如果还想确认核心模块可导入：
bash
python -c "from agentscope.agent import Agent; print('Agent import OK')"常见错误
Python 版本过低
ERROR: agentscope requires Python '>=3.11'原因：当前解释器低于 3.11。解决：用 uv venv --python 3.11 创建新的虚拟环境并激活， 或在 pyproject.toml / CI 里指定 requires-python = ">=3.11"。
缺少可选依赖
ModuleNotFoundError: No module named '...'原因：使用了需要 extra 的能力但未安装对应 extra。例如使用 RAG 时需要 rag extra，使用 Workspace 沙箱时需要 workspace extra。解决：按需补装：
bash
uv pip install 'agentscope[rag]'模型 API Key 未设置
KeyError: 'DASHSCOPE_API_KEY'原因：环境变量未导出，或 .env 文件未被加载。解决：确认 .env 已加入 .gitignore， 在代码入口用 python-dotenv 加载，或在启动前 export 对应变量。
python
# 使用 python-dotenv 加载 .env
from dotenv import load_dotenv
load_dotenv() # 读取项目根目录的 .env模型不支持 tool calling
Tool calling is not supported by this model原因：为 Agent 配置了工具，但所选模型不支持 function / tool calling。解决：换用支持 tool calling 的模型（如 Qwen-Max、GPT-4o、Claude 3.5 等），或移除工具配置。