AgentScope 中文教程：5 个真实场景快速开始（2026 版）

本文基于 AgentScope v2.0.8 版本编写，内容基于开源项目 modelscope/agentscope（Apache-2.0 License）翻译整理 + 原创中文场景 demo。 中文译注 + 原创 demo 版权归裕普网络有限公司所有。

---

一、AgentScope 是什么，为什么值得关注

AgentScope 是阿里通义实验室（ModelScope 团队）开源的多智能体框架。2026 年的国内 AI 开发生态里，它有几个别的框架替代不了的定位优势：

1. 中文原生：AgentScope 从第一天就是中文社区优先的项目——文档、issue 讨论、示例场景都对国内开发者友好。相比 LangGraph / CrewAI 这类英文优先的框架，它的上手摩擦天然更低。
2. 多 Agent 协作是一等公民：AgentScope 的 Msg 消息协议 + Pipeline / MsgHub 编排原语，天生为「多个 Agent 互相对话协作」设计，而不是「单 Agent + 工具」的链式模型。
3. 国产模型深度适配：Qwen / DashScope / DeepSeek 等模型的接入模板开箱即用，不需要自己包一层 OpenAI 兼容层。
4. Apache-2.0 许可：对商用和二次分发都友好（注意遵守 ATTRIBUTION 要求即可）。

截至 2026 年 9 月，AgentScope GitHub Stars 已突破 31k，是国内增长最快的开源 Agent 框架之一。

与 LangGraph 的关系

很多读者会问：已经有 LangGraph 了，为什么还要看 AgentScope？两者的核心差异：

两者不是替代关系，而是互补：需要「审批流 + 可恢复状态」选 LangGraph，需要「多个角色协作完成任务」选 AgentScope。

---

二、5 分钟环境准备

# 1. 创建虚拟环境（推荐 Python 3.10 / 3.11）
python3 -m venv agentscope-zh-env
source agentscope-zh-env/bin/activate

# 2. 安装 AgentScope（锁定 v2.0.8）
pip install agentscope==2.0.8

# 3. 验证安装
python3 -c "import agentscope; print(agentscope.__version__)"

注意：AgentScope 2.x 需要 Python ≥ 3.9。如果用 Qwen 系模型，先去 DashScope 控制台申请 API Key 并 export DASHSCOPE_API_KEY=sk-xxx。

最小可运行示例（单 Agent 问答）：

import agentscope
from agentscope_agent import ReActAgent

agentscope.init(model_configs=[
    {
        "config_name": "qwen_max",
        "model_type": "dashscope_chat",
        "model_name": "qwen-max",
        "api_key": "sk-xxx",
    }
])

agent = ReActAgent(
    name="助手",
    sys_prompt="你是一个乐于助人的中文 AI 助手。",
    model_config_name="qwen_max",
)
print(agent(reply="用一句话解释什么是多智能体系统"))

运行成功说明环境就绪。下面进入 5 个真实场景。

---

三、场景 1：多 Agent 协作（头脑风暴）

业务原型：产品提案评审——「产品经理」「架构师」「测试负责人」三个角色依次发言，各自从自己的视角补充观点。

核心 API：sequentialpipeline（顺序发言）+ MsgHub（共享话题）。

from agentscope.message import Msg
from agentscope.pipeline import sequentialpipeline
from agentscope.pipeline import MsgHub

pm = ReActAgent(name="产品经理", sys_prompt="你是产品经理，从用户价值角度分析提案。", model_config_name="qwen_max")
arch = ReActAgent(name="架构师", sys_prompt="你是系统架构师，从技术可行性与成本角度分析。", model_config_name="qwen_max")
qa = ReActAgent(name="测试负责人", sys_prompt="你是测试负责人，从质量风险角度补充。", model_config_name="qwen_max")

topic = Msg("user", "提案：在公司内部上线一个 AI 工单分派系统", "user")

with MsgHub(participants=[pm, arch, qa], announcement=topic):
    summary = sequentialpipeline([pm, arch, qa])

print(summary.content)

要点：

• MsgHub 内的 Agent 能看到彼此的发言（共享上下文），这是「协作」的关键；
• sequentialpipeline 返回最后一个 Agent 的输出——要拿到全部发言，可订阅 agentscope.logger。

完整可运行代码见交付包 demo/01_multi_agent/（含 README 中文说明 + 运行脚本）。

---

四、场景 2：工具调用（查天气 + 计算）

业务原型：客服 Agent 需要调用外部工具回答事实性问题。

from agentscope.formatter import OpenAIChatFormatter

def get_weather(city: str) -> str:
    """查询城市天气（示例 stub，生产环境接真实 API）"""
    return f"{city} 今天多云，18-26℃，东风 3 级"

agent = ReActAgent(
    name="客服",
    sys_prompt="你是客服助手，回答天气问题必须调用工具。",
    model_config_name="qwen_max",
    toolkit=toolkit,  # 注册 get_weather 后自动生成工具 schema
)

AgentScope 的 toolkit 会把 Python 函数签名自动转成工具描述，ReAct 循环里模型自行决定何时调用——不需要手写 if/else 分发逻辑。

完整代码见 demo/02_tool_calling/。

---

五、场景 3：中文地址识别（结构化抽取）

业务原型：电商/物流场景，把用户的自然语言地址解析成结构化字段。这是 AgentScope 中文能力的「主场」——Qwen 系模型对中文地址的分词和行政区划理解明显优于英文优先的模型。

prompt = """请把下面的地址解析成 JSON（province/city/district/detail）：
四川省南充市顺庆区人民中路一段 88 号 3 栋 2 单元 501 室"""

# ReActAgent + qwen-max 输出示例：
# {"province":"四川省","city":"南充市","district":"顺庆区","detail":"人民中路一段88号3栋2单元501室"}

注意让模型「只输出 JSON」时加上 few-shot 示例，可以显著降低格式错误率。交付包内 demo/03_chinese_address/ 提供了带校验的完整实现（解析失败自动重试一次）。

---

六、场景 4：工单分派（路由决策）

业务原型：IT 服务台收到工单后，先由「分派 Agent」判断类别（网络/数据库/账号/其他），再转给对应的专业 Agent 处理。

router = ReActAgent(
    name="分派员",
    sys_prompt="""你是 IT 服务台分派员。根据工单内容输出类别：
网络问题 → network；数据库 → db；账号权限 → account；其他 → general。只输出类别代码。""",
    model_config_name="qwen_max",
)

category = router(reply=ticket_text).content
handler = {"network": net_agent, "db": db_agent,
           "account": acc_agent, "general": gen_agent}[category.strip()]
result = handler(reply=ticket_text)

这是「路由模式」的最小实现。工单量上来后，可以演进为 MsgHub + 记忆模块，让分派员学习历史分派准确率。交付包 demo/04_ticket_dispatch/ 含 10 条模拟工单的测试集。

---

七、场景 5：RAG 检索增强问答

业务原型：企业内部知识库问答。AgentScope 提供了 RAGAgent，内置检索 → 重排 → 生成的完整链路。

from agentscope.rag import RAGAgent, Knowledge

kb = Knowledge.from_docs("docs/*.md", chunk_size=500, chunk_overlap=50)
rag_agent = RAGAgent(
    name="知识库助手",
    model_config_name="qwen_max",
    knowledge=kb,
    sys_prompt="基于检索到的资料回答。检索不到就说不知道，不要编造。",
)
print(rag_agent(reply="公司的差旅报销标准是什么？"))

中文知识库要点：chunk_size 按「字符数」而非「token 数」设置（中文一字一符，500 字符约等于 700-800 token，刚好落在 Qwen 的检索甜区）。

完整代码（含本地 Embedding + 重排）见 demo/05_rag/。

---

八、常见坑速查

更多错误码（初始化 / 模型加载 / 对话状态 / API 调用四大类）见配套文章《AgentScope 部署踩坑：常见错误中文解释》。

---

九、延伸阅读

• AgentScope 官方文档
• AgentScope GitHub 仓库
• ModelScope 模型社区
• 配套踩坑文：《AgentScope 部署踩坑：常见错误中文解释》

---

资源与声明

• 原项目：modelscope/agentscope
• 原项目许可证：Apache License 2.0（本店交付包内 LICENSES/ORIGINAL_LICENSE 附完整原文）
• 关于本店：本店提供「中文本地化增强包 / 打包整理服务」——包含上述 5 个场景完整可运行 demo（demo/01_multi_agent ~ 05_rag）、中文错误码库（errors-zh/ 四大类）、中文快速上手文档（docs-zh/）。增强包为本店原创整理工作，与原项目官方无关联；原项目本身可从其官方渠道免费获取。
• 本店增强包内容基于原项目 v2.0.8（commit b82253ba）整理，转载请注明原项目出处。

---

本文由裕普智汇 AI 智能体工厂整理发布。转载请注明出处。