AgentScope：超详细部署与使用教程

AgentScope 是阿里巴巴开源的生产级多智能体（Multi-Agent）应用开发框架，当前已演进到 2.0 版本。它面向「越来越具备自主行动能力的大模型」设计，提供 ReAct 推理-行动循环、工具调用（Toolkit）、多模型接入、上下文管理、事件系统、权限与人机协同（HITL）、长期记忆、隔离沙箱等完整抽象，并附带一套开箱即用的 Agent Service（FastAPI 后端 + 预置 Web UI），可直接把你的 Agent 变成多租户、多会话的在线应用。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

AgentScope 是一套「开发者中心（Developer-Centric）」的 Agent 应用框架。官方在 2.0 版本中明确提出：不再用严格的提示词（Prompt）和固执的编排流程去束缚大模型，而是充分利用模型自身的推理能力与工具使用能力，再用框架提供的工程抽象把这些能力组织成可观测、可调试、可部署的应用。

框架起源于阿里通义实验室团队的研究工作（相关论文 arXiv:2402.14034、arXiv:2508.16279），1.0 时代以「灵活、健壮的多智能体平台」著称，2.0 则转向生产可用：内置 Agent Service 后端、预置 Web UI、多租户与会话隔离、状态持久化、定时任务与后台任务卸载、飞书/Discord 等 IM 通道接入、RAG 服务、MCP 与 Skill 中心等。仓库已从 alibaba/agentscope 迁移至独立组织 agentscope-ai/agentscope（旧地址会自动跳转）。

1.2 核心功能

• ReAct Agent 循环：推理-行动（Reasoning-Acting）循环，支持结构化输出、实时中断与恢复、批量（串行/并发）工具执行。
• Toolkit 工具管理：把 Python 工具、MCP Server、Skill 统一注册为 Agent 可调用工具；内置编码工具集（Shell/Bash、文件编辑、搜索、Grep、Glob、Read、Write、Edit）以及任务规划工具。
• 多模型接入（Model）：统一接入 OpenAI、Anthropic、Gemini、DashScope（通义千问）、DeepSeek、Moonshot（Kimi）、火山引擎（Volcengine）、xAI、Ollama 等主流厂商的 Chat 模型，以及 Embedding、TTS、Realtime 语音模型。
• 上下文管理（Context）：通过内置中间件自动完成上下文压缩（Compaction）、工具结果卸载（Offload）、系统提示词/RAG/记忆注入，解决长上下文窗口爆掉的问题。
• 事件系统（Event System）：统一事件总线，把推理过程、工具调用、多模态内容（文本/图片/音频）实时流式推送到前端，是可视化调试与 Web UI 的基础。
• 权限与人机协同（Permission & HITL）：对工具与资源做细粒度权限控制，支持工具调用前人工确认（Confirmation）与免确认绕过模式（Bypass）。
• 中间件（Middleware）：可组合的钩子，挂载在回复、推理、行动、模型调用、权限检查、上下文压缩、系统提示词等各个环节。
• 长期记忆（Memory）：可切换后端的 Agentic 记忆，内置支持 ReMe、Mem0。
• 工作区/沙箱（Workspace / Sandbox）：隔离的工具与代码执行环境，支持本地、Docker、Apple Container、Bubblewrap、E2B、OpenSandbox、Daytona、K8s 多种后端。
• Agent Service（应用后端）：FastAPI 后端 + 预置 Web UI，开箱即得多租户、多会话隔离、SQL/NoSQL 状态持久化、定时任务与后台任务卸载。
• Agent Team 多智能体编排：Leader-Worker（主从）式团队协作，Leader 把任务委派给成员 Agent（TeamPipeline），内置团队工具与任务规划。
• 通道接入（Channels）：把 Agent 连接到飞书（Lark）、Discord 等 IM 平台，并支持自定义通道与消息路由。
• RAG 服务：Blob 存储、索引 Worker、多租户检索，作为独立服务提供知识库问答能力。
• MCP & Skill Hub：浏览 MCP Registry、ClawHub 等中心，一键安装 MCP Server 与 Skill 到自己的工具库。
• 前沿协议支持：A2A 协议（通过 A2AAgent 与任意远程 A2A Agent 对话）、Realtime 语音 Agent（WebRTC 实时语音对话，文本与语音共享同一会话历史）、SOP 标准作业流程（把多步任务固化为 SOP 运行）。

1.3 技术架构

下图是 AgentScope 官方 README 中的整体架构图：中央是 AgentScope 2.0 核心——Agent Service（后台任务管理、会话管理、用户鉴权、存储/DB 管理、工作区池）、Event System（消息与事件、事件流、人机协同）、Agent Engine（推理、批量行动、Toolkit、权限系统）、Workspace（本地文件系统、Docker、云沙箱）、Model（Chat Model / TTS / Realtime，含重试与降级）、Context Management（结构化压缩、上下文卸载）、Agent Middleware（推理/行动/回复/系统提示词）；外围一圈是生态集成：左侧是 Claude、DeepSeek、Gemini、OpenAI、Qwen、Azure、Ollama 等模型提供方，上方是 MySQL、PostgreSQL、MongoDB、OceanBase、Redis、Milvus、Qdrant、mem0 等存储与向量库，下方是 Nacos、RocketMQ、ARMS、LangSmith、Langfuse 等可观测与中间件，右侧是 Data-Juicer、OpenJudge、ASReMe、Trinity-RFT 等官方配套项目。

下图是官方 Web UI（Agent Service 前端）的实际界面截图：左侧为 Agent 列表与会话管理，顶部可切换模型（如 qwen3.6-max-preview）与 Bypass 权限模式，地址为 http://localhost:8000，可在对话框中直接向 Agent 下发任务。

二、环境要求

关键前置：AgentScope 只是「编排框架」，本身不自带大模型权重。你必须先在某个模型厂商平台申请 API Key（例如阿里云百炼申请 DashScope API Key），并设置为环境变量，否则 Agent 启动后无法对话。

三、部署方式

下面给出三种部署路径：① PyPI 快速安装（推荐，最快上手）→ ② 源码安装（二次开发）→ ③ Agent Service 完整部署（后端 + Web UI，做成在线应用）。

3.1 方式一：PyPI 安装（最快上手）

官方推荐使用 uv（Astral 出品的 Python 包管理器）。如果你的环境还没有 uv，可先安装：

# 安装 uv（官方推荐方式；也可用 pip install uv）
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

然后创建虚拟环境并安装 AgentScope：

# 1) 创建并激活虚拟环境（Python 3.11+）
uv venv --python 3.11 .venv
source .venv/bin/activate

# 2) 安装 AgentScope 核心包
uv pip install agentscope

如果你更习惯标准 pip，等价命令为：

python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install agentscope

配置模型 API Key（以 DashScope 通义千问为例）：

# 把下面的 sk-xxxx 换成你在阿里云百炼申请的真实 Key
export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

# 如使用 OpenAI / Anthropic / Gemini / DeepSeek / Moonshot 等，对应设置：
# export OPENAI_API_KEY="sk-xxxx"
# export ANTHROPIC_API_KEY="sk-ant-xxxx"
# export GEMINI_API_KEY="xxxx"
# export DEEPSEEK_API_KEY="sk-xxxx"
# export MOONSHOT_API_KEY="sk-xxxx"

建议把环境变量写入 ~/.bashrc 或项目 .env 文件长期生效；Windows 下用 set DASHSCOPE_API_KEY=sk-xxxx（CMD）或 $env:DASHSCOPE_API_KEY="sk-xxxx"（PowerShell）。

3.2 方式二：源码安装（二次开发 / 体验最新特性）

# 1) 拉取源码（官方仓库已迁移到 agentscope-ai 组织）
git clone -b main https://github.com/agentscope-ai/agentscope.git
cd agentscope

# 2) 以可编辑模式安装
uv pip install -e .

说明：

• 源码目录下带有 examples/ 示例工程（examples/agent_service、examples/web_ui、examples/realtime、examples/a2a 等），拉源码后可以直接跑这些官方示例。
• main 分支是官方默认分支（开发主线）；如需稳定版建议使用 Release Tag（如 v2.0.10）对应的提交。
• 若要贡献代码，请阅读仓库根目录的 CONTRIBUTING.md。

3.3 方式三：Agent Service 完整部署（后端 + 预置 Web UI）

这是把 Agent 变成「多租户在线应用」的官方路径，包含一个 FastAPI 后端和一个预置的 Web 前端。

步骤 1：启动后端服务

# 先按方式二克隆源码
cd agentscope/examples/agent_service

# 确保已激活虚拟环境，且 agentscope 已安装
python main.py

后端启动后默认监听本机端口（官方示例默认地址为 http://localhost:8000，具体以该示例 main.py 配置为准），提供 Agent 会话、多租户、持久化、定时任务等 REST 接口。

步骤 2：启动 Web UI 前端

新开一个终端：

cd agentscope/examples/web_ui

# 安装前端依赖（如未安装 pnpm：npm install -g pnpm）
pnpm install

# 以开发模式启动前端
pnpm dev

按照终端提示的地址（通常为 http://localhost:5173 等 Vite 开发端口，以实际输出为准）在浏览器打开，即可看到类似前文截图的 Web UI，创建 Agent、切换模型、开始会话。

步骤 3：生产化部署提示

• 后端是 FastAPI 应用，生产环境建议用 uvicorn / gunicorn 启动并前置 Nginx 反代（具体部署参数以官方文档「Agent Service」章节为准）。
• 持久化存储可配置 SQL/NoSQL 后端（官方支持 SQL 与 NoSQL 两种状态持久化，见文档 Storage Backend 一节），不要在生产中用默认内存态。
• 对外暴露前务必配置用户鉴权（Agent Service 内置 User Authentication & Authorization），并按需开启 HTTPS。

3.4 验证部署成功

# 1) 验证 Python 包安装成功
python -c "import agentscope; print(agentscope.__version__)"

# 2) 验证 API Key 已注入
echo $DASHSCOPE_API_KEY

然后运行官方最小示例（控制台对话 Agent）：

# quickstart.py
import os, asyncio
from agentscope.agent import Agent
from agentscope.console import launch_console
from agentscope.tool import Toolkit, Bash, Grep, Glob, Read, Write, Edit
from agentscope.credential import DashScopeCredential
from agentscope.model import DashScopeChatModel


async def main() -> None:
    agent = Agent(
        name="Friday",
        system_prompt="You're a helpful assistant named Friday.",
        model=DashScopeChatModel(
            credential=DashScopeCredential(
                api_key=os.environ["DASHSCOPE_API_KEY"]
            ),
            model="qwen3.6-plus",
        ),
        toolkit=Toolkit(
            tools=[Bash(), Grep(), Glob(), Read(), Write(), Edit()]
        ),
    )
    # 进入终端控制台对话：流式输出、工具调用确认、Ctrl+C 中断均已内置
    await launch_console(agent)


asyncio.run(main())

python quickstart.py

预期：终端出现 Agent 提示符，输入「你好，请介绍一下你自己」后，Agent 流式输出回复；当 Agent 需要调用工具（如执行 Bash）时会弹出确认提示。能对话即说明 Python 包 + 模型 API + 工具链 整条链路部署成功。

四、使用方法

4.1 基础用法：第一个 Agent（Console 模式）

最小可用 Agent 由三要素构成：name + system_prompt（人设）、model（大模型）、toolkit（可用工具）。

from agentscope.agent import Agent
from agentscope.credential import DashScopeCredential
from agentscope.model import DashScopeChatModel
from agentscope.tool import Toolkit, Read, Write, Bash
import os

agent = Agent(
    name="Friday",
    system_prompt="You are a helpful assistant named Friday. Use tools when needed.",
    model=DashScopeChatModel(
        credential=DashScopeCredential(api_key=os.environ["DASHSCOPE_API_KEY"]),
        model="qwen3.6-plus",
    ),
    toolkit=Toolkit(tools=[Read(), Write(), Bash()]),
)

随后在脚本中通过 launch_console(agent) 进入交互式终端对话；也可以在自己的业务代码里直接调用 Agent 的对话接口（具体同步/异步调用 API 以官方文档「Agent 构建块」章节为准）。

4.2 常用 API 与配置

1）切换模型厂商：只需替换 Model 类与对应的 Credential：

# OpenAI
from agentscope.model import OpenAIChatModel
from agentscope.credential import OpenAICredential

model = OpenAIChatModel(
    credential=OpenAICredential(api_key=os.environ["OPENAI_API_KEY"]),
    model="gpt-4o",
)

# 本地 Ollama（无需 API Key）
from agentscope.model import OllamaChatModel
model = OllamaChatModel(model="qwen2.5:7b")

2）注册自定义 Python 工具：用 @tool 装饰一个普通 Python 函数即可（装饰器导入路径与具体参数以官方文档 Toolkit 章节为准）。

from agentscope.tool import tool

@tool
def get_weather(city: str) -> str:
    """Return the weather of a city."""
    return f"{city}: 晴，22℃"

3）接入 MCP Server：在 Toolkit 中注册 MCP Server 后，Agent 即可调用 MCP 暴露的工具（连接方式见官方文档 Toolkit / MCP 章节）。

4）开启模型路由（Model Router）：官方支持 ModelRouterMiddleware，为每一轮回复自动选择最合适的 Chat 模型，适合「大模型推理 + 小模型简单任务」混部降本。

5）权限模式：默认工具调用需人工确认；在 Web UI 右上角可切换 Bypass 模式，Agent 端到端自动执行而不暂停等待确认（仅限可信场景）。

4.3 进阶功能

• Agent Team（多智能体团队）：Leader Agent 把复杂任务拆解并委派给成员 Agent，配合内置团队工具做任务规划与进度跟踪（对应 TeamPipeline，见官方 Building Blocks / Pipeline 文档）。
• A2A 协议：通过 A2AAgent 与任意远程 A2A 协议的 Agent 互相对话，示例见 examples/a2a。
• Realtime 语音 Agent：支持 DashScope、OpenAI、Gemini、xAI 的 Realtime API，通过 WebRTC 做端到端实时语音对话，文本与语音共享同一会话历史，示例见 examples/realtime。
• SOP 标准作业流程：把多步任务固化为标准操作程序，在框架与 Agent Service 中按 SOP 运行，适合企业内重复性流程自动化。
• RAG 服务：Agent Service 内置 Blob 存储与索引 Worker，可直接构建多租户知识库问答。
• IM 通道接入：把 Agent 接入飞书群、Discord，用户在 IM 里直接 @Agent 使用。
• 后台任务卸载：长耗时工具调用转入后台执行，完成后唤醒 Agent 继续会话（事件驱动恢复）。
• 上下文自动压缩：长对话接近上下文上限时，中间件自动做结构化压缩与工具结果卸载，无需手动裁剪历史。

4.4 适用场景

• 企业内部智能体助手：接入飞书/Discord，连知识库与业务系统工具；
• 自动化研发助手：内置 Shell/文件编辑/搜索工具，Agent 直接在沙箱里改代码、跑命令；
• 多智能体协作系统：研究报告生成、深度调研（Deep Research）、数据分析流水线；
• 语音对话应用：客服、语音陪伴、实时语音交互产品；
• 把现有 Prompt 工程升级为可观测、可调试、可部署的生产级 Agent 服务。

五、常见问题排查（FAQ）

Q1：安装时报错 ERROR: Package 'agentscope' requires a different Python，或 requires-python = '>=3.11' 失败 - 原因：AgentScope 2.0 官方要求 Python 3.11+，系统自带 Python 3.8/3.10 不满足。 - 解决：python3 --version 确认版本；用 uv venv --python 3.11 .venv 指定 3.11+ 环境，或先通过官方源安装 Python 3.11/3.12 再建虚拟环境。

Q2：运行示例时报 KeyError: 'DASHSCOPE_API_KEY' 或 api_key not provided - 原因：AgentScope 本身不内置模型，未设置模型 API Key。 - 解决：export DASHSCOPE_API_KEY="sk-xxx"（或对应厂商的 Key），并确认当前终端已生效；建议写入 .env 或 shell 配置文件。

Q3：uv: command not found - 原因：未安装 uv。 - 解决：执行官方安装脚本 curl -LsSf https://astral.sh/uv/install.sh | sh && source $HOME/.local/bin/env；或直接放弃 uv，改用标准 pip install agentscope。

Q4：Web UI 启动报错 pnpm: command not found - 原因：官方前端示例使用 pnpm，环境未安装。 - 解决：npm install -g pnpm（需先有 Node.js 18+）；或按示例 README 提示改用 npm install && npm run dev。

Q5：Agent 对话超时 / 连接被拒绝（调用 DashScope、OpenAI 等 API 失败） - 原因：网络无法到达模型 API，或 Key 无额度/失效。 - 解决：curl https://dashscope.aliyuncs.com/api/v1/services -H "Authorization: Bearer $DASHSCOPE_API_KEY" 类方式自测连通性；国内网络优先 DashScope；如在公司代理后，需配置 HTTPS_PROXY 环境变量。

Q6：Agent Service 后端启动后浏览器打不开 http://localhost:8000 - 原因：后端未启动成功、端口被占用，或防火墙拦截。 - 解决：python main.py 看终端是否报错；ss -lntp | grep 8000 确认端口；如被占用，改示例配置端口（以官方示例为准）。

Q7：工具调用一直等待人工确认，体验像卡住 - 原因：这是权限系统的默认安全行为——每次工具调用都要确认。 - 解决：可信调试环境下在 Web UI 右上角切换 Bypass 模式；或按文档配置 Permission 规则对特定工具免确认。

Q8：长对话到后面 Agent「忘记前面说过的话」或报上下文超长 - 原因：对话历史超出模型上下文窗口。 - 解决：AgentScope 内置 Context 压缩与工具结果卸载中间件，确认已启用；或切换更大上下文模型、接入长期记忆（ReMe/Mem0）。

六、部署注意事项与最佳实践

1. Python 版本底线：全团队统一 Python 3.11+，避免「我机器上能跑」的环境漂移；建议用 uv 锁环境（uv.lock）。
2. API Key 管理：禁止把 Key 硬编码进代码仓库；用环境变量或 Secret 管理；生产环境走密钥管理服务。
3. 沙箱安全：Agent 自带 Shell/文件编辑工具，生产环境务必把工具执行放在隔离沙箱（Docker / E2B / K8s），不要直接在宿主机跑；权限系统默认开启，不要图省事全局 Bypass。
4. 生产 Agent Service 不要裸奔：FastAPI 后端要前置鉴权、HTTPS、Nginx；持久化切换到真实 SQL/NoSQL；定时任务与后台任务要监控。
5. 模型成本控制：长任务用 ModelRouterMiddleware 把简单请求路由到小模型；关注各厂商 Token 账单。
6. 版本跟进：2.0 迭代很快（News 栏目每月都有新特性），生产前锁定 Release 版本（如 v2.0.10），不要直接跟踪 main 分支。
7. 可观测性：官方架构图中已集成 LangSmith、Langfuse、ARMS、OpenTelemetry 等，生产环境建议接入其一做链路追踪。
8. 多租户与数据隔离：Agent Service 多租户能力要正确配置存储与隔离策略，避免不同租户会话串数据。

七、参考资料

• GitHub 仓库（新地址）：https://github.com/agentscope-ai/agentscope
• 旧地址（自动跳转）：https://github.com/alibaba/agentscope
• 官方文档站：https://docs.agentscope.io/
• 中文 README：https://github.com/agentscope-ai/agentscope/blob/main/README_zh.md
• PyPI 页面：https://pypi.org/project/agentscope/
• Release 列表：https://github.com/agentscope-ai/agentscope/releases
• Agent Service 文档：https://docs.agentscope.io/latest/en/deploy/agent-service
• A2A 示例：https://github.com/agentscope-ai/agentscope/tree/main/examples/a2a
• Realtime 语音示例：https://github.com/agentscope-ai/agentscope/tree/main/examples/realtime
• 论文：AgentScope 1.0（arXiv:2508.16279）、AgentScope（arXiv:2402.14034）