AgentScope 入门到精通教程

基于 AgentScope 稳定版（v1.0，文档站 doc.agentscope.io）。本教程所有代码均对应当前 v1.0 API；主干正在向 2.0 演进，文末单独说明 2.0 的变化与迁移要点。

AgentScope 由阿里巴巴达摩院（DAMO Academy）开源，是一个生产可用的多智能体（Agent）框架，强调"可见、可理解、可信任"的智能体开发。它的设计哲学是顺应模型能力的增长——更多依赖大模型自身的推理与工具调用能力，而不是用僵硬的提示词和死板的编排去约束模型。

---

目录

第一部分 · 入门

1. AgentScope 是什么，适合做什么
2. 安装与环境准备
3. 核心概念速览
4. 你的第一个 Agent（Hello AgentScope）

第二部分 · 核心组件
5. 消息 Msg
6. 模型 Model（接入各家大模型）
7. 提示词格式化 Formatter
8. 记忆 Memory（短期与长期）
9. 工具 Toolkit
10. ReActAgent 全参数详解

第三部分 · 进阶
11. 结构化输出
12. 多智能体编排（MsgHub / Pipeline / 路由 / Handoff / 并发）
13. MCP 工具集成
14. Plan 规划能力
15. RAG 检索增强
16. 自定义 Agent（从零继承 AgentBase）
17. Hooks 与 Middleware
18. 人机协同与实时中断
19. 状态与会话管理

第四部分 · 精通与生产
20. AgentScope Studio：可视化、调试与 Tracing
21. 评测 Evaluation
22. 部署与服务化（Runtime / AgentApp）
23. A2A：跨框架多智能体协作
24. 模型微调与 Agentic RL（Tuner）
25. 实时语音 Agent
26. AgentScope 2.0 变化与迁移
27. 学习路径与资源

---

第一部分 · 入门

1. AgentScope 是什么，适合做什么

AgentScope 是一个用 Python 编写的智能体应用框架。一句话概括：它帮你把"大模型 + 工具 + 记忆 + 多智能体协作"组装成可上线的应用。

它的核心特点：

• 简单：内置开箱即用的 ReAct（Reasoning + Acting，推理-行动）智能体，5 分钟就能跑通第一个带工具的 Agent。
• 可扩展：原生支持 MCP、A2A 等协议；提供 MsgHub 消息中心做多智能体编排；工具、记忆、可观测性都有丰富的生态集成。
• 生产可用：可本地运行、可作为 Serverless 部署到云上、也可部署到 K8s 集群，内置 OpenTelemetry（OTel）可观测性支持。
• 全异步：v1.0 起核心 API 基于 async/await，天然适合高并发、流式输出、可中断的场景。

典型适用场景：智能助手 / Copilot、自动化任务执行（代码执行、文件操作、浏览器操作）、多智能体辩论与协作、带长期记忆的对话机器人、RAG 知识问答、语音交互应用等。

和别的框架比：相比 LangChain 偏"链式编排"、AutoGen 偏"对话编排"，AgentScope 的取向是把控制权更多交还给模型，框架只提供清晰、可观测、可中断的底座，因此在"模型越来越强"的趋势下迭代成本更低。

---

2. 安装与环境准备

AgentScope 要求 Python 3.10 及以上。

从 PyPI 安装（推荐）

pip install agentscope
# 或者使用 uv（更快）
uv pip install agentscope

从源码安装（想读源码 / 跟最新主干）

git clone -b main https://github.com/agentscope-ai/agentscope.git
cd agentscope
pip install -e .
# 或 uv pip install -e .

准备模型 API Key

教程以阿里云百炼（DashScope，通义千问 Qwen 系列）为例，因为它和 AgentScope 同源、文档示例最全。注册后拿到 API Key，设置环境变量：

export DASHSCOPE_API_KEY="sk-你的key"

AgentScope 同样支持 OpenAI、Anthropic、Gemini、Ollama（本地模型）等，见第 6 节。换模型只需要换 Model 和对应的 Formatter 两个类。

---

3. 核心概念速览

理解这 6 个概念，你就理解了 AgentScope 的全部骨架：

概念	类 / 模块	作用
消息 Msg	agentscope.message.Msg	智能体之间、人与智能体之间传递的最小单位，带 name/content/role
模型 Model	agentscope.model.*ChatModel	封装具体大模型 API 调用，负责"生成"
格式化器 Formatter	agentscope.formatter.*Formatter	把消息列表组装成模型能吃的 prompt 格式，必须和模型匹配
记忆 Memory	agentscope.memory.*	存储对话历史（短期）与跨会话知识（长期）
工具箱 Toolkit	agentscope.tool.Toolkit	注册、管理、调用工具函数
智能体 Agent	agentscope.agent.ReActAgent 等	把上面几样组装起来，执行"推理→调用工具→再推理"的循环

多智能体编排再加一个：

| 消息中心 MsgHub | agentscope.pipeline.MsgHub | 让多个 Agent 互相广播消息、协同工作 |

关键心智模型：一个 ReActAgent = 模型 + 格式化器 +（可选）工具箱 +（可选）记忆。你给它一条 Msg，await 它，它内部会自己决定要不要调工具、调几次，最后返回一条 Msg。

---

4. 你的第一个 Agent（Hello AgentScope）

下面这段代码创建一个叫 Jarvis 的智能体，给它一个"执行 Python 代码"的工具，然后让它跑一句 Hello World。

import asyncio
import os

from agentscope.agent import ReActAgent
from agentscope.formatter import DashScopeChatFormatter
from agentscope.memory import InMemoryMemory
from agentscope.message import Msg
from agentscope.model import DashScopeChatModel
from agentscope.tool import Toolkit, execute_python_code


async def main() -> None:
    # 1) 准备工具箱，注册"执行 Python 代码"工具
    toolkit = Toolkit()
    toolkit.register_tool_function(execute_python_code)

    # 2) 创建 ReAct 智能体
    jarvis = ReActAgent(
        name="Jarvis",
        sys_prompt="你是一个名叫 Jarvis 的得力助手。",
        model=DashScopeChatModel(
            model_name="qwen-max",
            api_key=os.environ["DASHSCOPE_API_KEY"],
            stream=True,            # 流式输出
            enable_thinking=False,  # 是否开启深度思考（Qwen3 系列支持）
        ),
        formatter=DashScopeChatFormatter(),  # 必须和模型匹配
        toolkit=toolkit,
        memory=InMemoryMemory(),    # 短期记忆，记住本轮对话
    )

    # 3) 构造一条用户消息并发给智能体
    msg = Msg(
        name="user",
        content="嗨 Jarvis，用 Python 打印 Hello World。",
        role="user",
    )

    # 4) await 调用智能体，它会自己决定调用工具
    await jarvis(msg)


asyncio.run(main())

运行后你会在控制台看到智能体的"推理过程"：它先输出一个 tool_use（调用 execute_python_code），系统返回 tool_result，最后它用自然语言告诉你执行成功并打印了 Hello World。这就是 ReAct 循环：推理（Reasoning）→ 行动（Acting）→ 观察结果 → 再推理，直到任务完成。

要点拆解：

• 所有 Agent 调用都是异步的，必须 await，并放在 asyncio.run() 里。
• model 和 formatter 要成对匹配（DashScope 模型 → DashScope 格式化器）。
• await jarvis(msg) 返回的其实是一条 Msg（智能体的最终回复），你可以接住它：reply = await jarvis(msg)。

---

第二部分 · 核心组件

5. 消息 Msg

Msg 是一切交互的载体。三个核心字段：

from agentscope.message import Msg

msg = Msg(
    name="user",        # 发送者名字
    content="你好",      # 内容，可以是字符串，也可以是多模态内容块列表
    role="user",        # 角色：'user' / 'assistant' / 'system'
)

• name vs role：role 是大模型协议层面的角色；name 是"谁说的"。在多智能体场景下多个 Agent 都是 assistant 角色，但 name 不同（Alice、Bob……），这正是多智能体能区分彼此发言的关键。
• 多模态内容：content 除了字符串，还可以是内容块列表，支持文本、图片、音频等。
• 结构化结果：当你要求 Agent 输出结构化数据时，结果会放在 msg.metadata（见第 11 节）。

# 读取智能体回复
reply = await agent(msg)
print(reply.name)                 # 智能体名字
print(reply.get_text_content())   # 取纯文本内容
print(reply.metadata)             # 结构化输出 / 元数据

---

6. 模型 Model（接入各家大模型）

AgentScope 为每家模型提供一个 *ChatModel 类，常见的有：

提供商	模型类	对应 Formatter
阿里云百炼 / Qwen	DashScopeChatModel	DashScopeChatFormatter
OpenAI	OpenAIChatModel	OpenAIChatFormatter
Anthropic	AnthropicChatModel	AnthropicChatFormatter
Google Gemini	GeminiChatModel	GeminiChatFormatter
Ollama（本地）	OllamaChatModel	OllamaChatFormatter

例如切换到 OpenAI：

from agentscope.model import OpenAIChatModel
from agentscope.formatter import OpenAIChatFormatter

model = OpenAIChatModel(
    model_name="gpt-4o",
    api_key=os.environ["OPENAI_API_KEY"],
    stream=True,
)
formatter = OpenAIChatFormatter()

常用参数：

• model_name：模型名。
• api_key：密钥。
• stream：是否流式输出（True 时逐字返回，体验更好）。
• enable_thinking：是否开启深度思考（部分模型如 Qwen3 支持）。

本地模型：用 OllamaChatModel 接 Ollama，可以完全离线跑开源模型，适合数据敏感或省钱场景。

也可以单独直接调用模型（不经过 Agent），用来理解底层：

prompt = await formatter.format([
    Msg("system", "你是助手", "system"),
    Msg("user", "讲个冷笑话", "user"),
])
response = await model(prompt)
print(response.content)

---

7. 提示词格式化 Formatter

Formatter 的职责：把一串 Msg 转成具体模型 API 要求的请求格式。它必须和模型配套，否则会报格式错误。

两类常用 Formatter：

• 单智能体对话：DashScopeChatFormatter（用户 ↔ 助手，一对一）。
• 多智能体对话：DashScopeMultiAgentFormatter。当一个 Agent 会收到来自多个不同 name 的消息时（比如辩论里的主持人），必须用多智能体版本，否则模型分不清谁是谁。

from agentscope.formatter import (
    DashScopeChatFormatter,        # 单智能体
    DashScopeMultiAgentFormatter,  # 多智能体
)

经验法则：只有"用户和一个助手"的简单对话用 ChatFormatter；只要场景里有第三方或多个发言者，就用 MultiAgentFormatter。

---

8. 记忆 Memory（短期与长期）

短期记忆

InMemoryMemory 把当前会话的消息存在内存里，是最常用的短期记忆：

from agentscope.memory import InMemoryMemory

memory = InMemoryMemory()
await memory.add(msg)              # 加入一条消息
history = await memory.get_memory() # 取出全部历史

把它传给 ReActAgent(memory=memory) 后，Agent 每轮都会带上历史，从而"记得"之前说过什么。v1.0 的 ReActAgent 还支持记忆自动压缩，对话很长时会自动总结压缩，避免超出上下文窗口。框架也支持把记忆落库到关系型数据库、Redis 等做持久化。

长期记忆

长期记忆用于跨会话保留知识（例如记住"用户喜欢喝美式"）。通过 long_term_memory 和 long_term_memory_mode 配置：

agent = ReActAgent(
    name="Friday",
    sys_prompt="...",
    model=model,
    formatter=formatter,
    long_term_memory=some_long_term_memory,   # 长期记忆实例
    long_term_memory_mode="both",             # 见下表
)

三种模式：

模式	含义
agent_control	由智能体自己决定何时检索、何时写入长期记忆（更智能，但靠模型判断）
static_control	每轮回复开始时自动检索、结束时自动写入（更可控）
both	同时启用上面两种

阿里还开源了配套的 ReMe（Retrieval-enhanced Memory） 记忆管理组件，可与 AgentScope 集成，提供更强的长期记忆检索能力。

---

9. 工具 Toolkit

工具是 Agent 的"手脚"。Toolkit 负责注册和管理工具。

注册内置工具

from agentscope.tool import Toolkit, execute_python_code, execute_shell_command

toolkit = Toolkit()
toolkit.register_tool_function(execute_python_code)
toolkit.register_tool_function(execute_shell_command)

自定义工具

工具就是一个普通函数（可以是同步或异步），返回 ToolResponse。函数的 docstring 和类型注解会被框架用来生成工具描述给模型看，所以一定要写清楚：

from agentscope.tool import Toolkit, ToolResponse
from agentscope.message import TextBlock

def get_weather(city: str) -> ToolResponse:
    """查询某个城市的当前天气。

    Args:
        city (str): 城市名，例如 "北京"。
    """
    # 这里写真实的查询逻辑，演示用假数据
    result = f"{city} 今天晴，25 摄氏度。"
    return ToolResponse(
        content=[TextBlock(type="text", text=result)],
    )

toolkit = Toolkit()
toolkit.register_tool_function(get_weather)

ReActAgent 支持的工具能力：

• 同步 / 异步工具函数都支持。
• 流式工具响应：工具可以边算边返回。
• 有状态工具管理：工具之间可以共享状态。
• 并行工具调用：parallel_tool_calls=True 时一轮内可同时调多个工具。
• 元工具（meta tool）：enable_meta_tool=True 时，允许智能体自己动态管理（增删）工具。

---

10. ReActAgent 全参数详解

ReActAgent 是日常开发最常用的类。完整可配置参数：

参数	必填	说明
name	✅	智能体名字
sys_prompt	✅	系统提示词，定义角色与行为
model	✅	使用的模型
formatter	✅	提示词格式化器，需与模型匹配
toolkit		工具箱
memory		短期记忆
long_term_memory		长期记忆
long_term_memory_mode		agent_control / static_control / both
enable_meta_tool		是否开启元工具，让 Agent 自管理工具
parallel_tool_calls		是否允许并行调用工具
max_iters		ReAct 循环最大迭代次数（防止无限循环）
plan_notebook		规划笔记本，启用任务分解能力（见第 14 节）
print_hint_msg		是否打印规划模块产生的提示消息

一个比较完整的配置示例：

agent = ReActAgent(
    name="Friday",
    sys_prompt="你是一个严谨、会用工具的助手 Friday。",
    model=DashScopeChatModel(
        model_name="qwen-max",
        api_key=os.environ["DASHSCOPE_API_KEY"],
        stream=True,
    ),
    formatter=DashScopeChatFormatter(),
    toolkit=toolkit,
    memory=InMemoryMemory(),
    parallel_tool_calls=True,
    max_iters=10,
)

---

第三部分 · 进阶

11. 结构化输出

很多时候你不想要一段自然语言，而是想要确定结构的数据（比如 JSON 给下游程序用）。AgentScope 用 Pydantic 模型来约束输出：调用 Agent 时传入 structured_model，结果会回填到 msg.metadata。

from pydantic import BaseModel, Field

class WeatherReport(BaseModel):
    """天气报告结构。"""
    city: str = Field(description="城市名")
    temperature: float = Field(description="摄氏温度")
    condition: str = Field(description="天气状况，如 晴/雨")

reply = await agent(
    Msg("user", "查一下北京天气，按结构化格式返回", "user"),
    structured_model=WeatherReport,
)

# 结构化结果在 metadata 里
print(reply.metadata["city"])         # 北京
print(reply.metadata["temperature"])  # 25.0
print(reply.metadata["condition"])    # 晴

框架内部会引导模型按 schema 输出；若模型输出不合法，会自动检测并要求模型修正，保证你拿到的是符合类型的结构化数据。这在"让多个 Agent 做决策、再由程序读取决策结果"的流程里特别有用（参考第 12 节辩论里的主持人）。

---

12. 多智能体编排（MsgHub / Pipeline / 路由 / Handoff / 并发）

这是 AgentScope 最有特色的部分。多个 Agent 如何协作，靠的是消息广播和管道编排。

12.1 MsgHub：消息中心

MsgHub 是一个异步上下文管理器。把若干 Agent 作为 participants 放进去，任何一个 participant 的回复都会自动广播给其他所有 participant——也就是它们能"听见"彼此说话。

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

async with MsgHub(participants=[alice, bob, charlie]):
    await alice(Msg("user", "请陈述你的观点", "user"))
    # alice 的回复自动被 bob、charlie 看到
    await bob(Msg("user", "请回应 alice", "user"))
    # bob 的回复又被 alice、charlie 看到……

完整示例：多智能体辩论。两位辩手 Alice、Bob 围绕一个题目辩论，主持人用结构化输出判定是否结束：

import asyncio, os
from pydantic import BaseModel, Field
from agentscope.agent import ReActAgent
from agentscope.formatter import DashScopeMultiAgentFormatter
from agentscope.message import Msg
from agentscope.model import DashScopeChatModel
from agentscope.pipeline import MsgHub

topic = "先有鸡还是先有蛋？"

def make_debater(name: str) -> ReActAgent:
    return ReActAgent(
        name=name,
        sys_prompt=f"你是辩手 {name}，围绕题目辩论：{topic}",
        model=DashScopeChatModel("qwen-max", api_key=os.environ["DASHSCOPE_API_KEY"], stream=False),
        formatter=DashScopeMultiAgentFormatter(),  # 多智能体必须用这个
    )

alice, bob = make_debater("Alice"), make_debater("Bob")

moderator = ReActAgent(
    name="主持人",
    sys_prompt=f"你是辩论主持人，评判双方关于「{topic}」的发言并决定是否得出结论。",
    model=DashScopeChatModel("qwen-max", api_key=os.environ["DASHSCOPE_API_KEY"], stream=False),
    formatter=DashScopeMultiAgentFormatter(),
)

class Judge(BaseModel):
    finished: bool = Field(description="辩论是否结束")
    answer: str | None = Field(description="若结束，给出结论", default=None)

async def run():
    while True:
        # 辩手互相能听见，主持人也在场
        async with MsgHub(participants=[alice, bob, moderator]):
            await alice(Msg("user", "你是正方，请陈述观点", "user"))
            await bob(Msg("user", "你是反方，请反驳并给出观点", "user"))
        # 主持人单独判定（辩手不需要听见主持人的内部判断）
        judge = await moderator(
            Msg("user", "本轮结束，能得出结论吗？", "user"),
            structured_model=Judge,
        )
        if judge.metadata.get("finished"):
            print("结论：", judge.metadata.get("answer"))
            break

asyncio.run(run())

注意主持人是放在 MsgHub 外面单独调用的——因为辩手不需要听到主持人的内部判断。"在不在同一个 MsgHub 里"就是控制信息可见范围的开关。

12.2 Pipeline：顺序 / 并发管道

agentscope.pipeline 还提供管道工具：

from agentscope.pipeline import sequential_pipeline

# 顺序执行：上一个 Agent 的输出作为下一个的输入
result = await sequential_pipeline(
    agents=[agent_a, agent_b, agent_c],
    msg=Msg("user", "开始任务", "user"),
)

• 顺序（sequential）：A → B → C 串行。
• 并发（concurrent）：多个 Agent 同时处理同一输入，适合"多人投票"“并行检索”，详见官方 Concurrent Agents 教程。

12.3 路由（Routing）与交接（Handoff）

• 路由：一个"调度 Agent"根据输入内容，决定把任务分发给哪个专家 Agent（客服分流、意图识别后转交）。
• Handoff（交接）：一个 Agent 在处理过程中把控制权移交给另一个更合适的 Agent，常用结构化输出 + 工具实现。

这两种模式本质都是"用一个 Agent 的输出来决定下一步调用谁"，官方教程 Routing / Handoffs 有完整范式可直接套用。

---

13. MCP 工具集成

MCP（Model Context Protocol）是一个让 Agent 接入外部工具/服务的标准协议。AgentScope 可以把 MCP 服务器暴露的工具，当作本地可调用函数来用，非常灵活。

import os
from agentscope.mcp import HttpStatelessClient
from agentscope.tool import Toolkit

async def use_mcp():
    # 1) 连接 MCP 服务器（这里用高德地图 MCP 为例）
    client = HttpStatelessClient(
        name="gaode_mcp",
        transport="streamable_http",
        url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
    )

    # 2) 把某个 MCP 工具拿成一个"本地函数"
    func = await client.get_callable_function(func_name="maps_geo")

    # 用法一：直接当普通函数调用
    await func(address="天安门广场", city="北京")

    # 用法二：注册进工具箱，交给 Agent 使用
    toolkit = Toolkit()
    toolkit.register_tool_function(func)

这种"细粒度 MCP 控制"的好处：你可以挑选单个 MCP 工具、和本地工具自由组合，甚至把多个工具包装成一个更复杂的工具。除了 MCP，AgentScope 也支持 A2A（Agent-to-Agent） 协议做跨服务的智能体协作（见第 23 节）。

---

14. Plan 规划能力

面对复杂的多步任务，让模型一步到位往往不靠谱。AgentScope 提供 PlanNotebook（规划笔记本）：智能体把大目标拆解成有序、可追踪的子任务，逐步执行，还能创建、修改、暂停、恢复多个并行的计划。

启用方式：给 ReActAgent 传 plan_notebook：

from agentscope.plan import PlanNotebook

plan_notebook = PlanNotebook(max_subtasks=15)

agent = ReActAgent(
    name="项目助手",
    sys_prompt="你负责规划并执行复杂任务。",
    model=model,
    formatter=formatter,
    toolkit=toolkit,
    plan_notebook=plan_notebook,   # 开启规划能力
    print_hint_msg=True,           # 打印每步的规划提示
)

适合"做一个完整项目""多步骤数据处理"这类需要系统性推进的任务。

---

15. RAG 检索增强

RAG（Retrieval-Augmented Generation）让 Agent 先从知识库检索相关内容，再据此回答，解决"模型不知道你私有知识"的问题。AgentScope 提供完整的 RAG 支持，核心组件：

• Embedding 模型：把文本转成向量（agentscope.embedding）。
• 向量存储：支持多种后端（如阿里云 MySQL 向量存储等）。
• 检索器：根据问题检索 top-k 相关文档片段，注入到 prompt。

典型流程：文档切分 → 向量化 → 入库 → 查询时检索 → 把检索结果作为上下文交给 Agent 回答。具体 API 见官方 RAG 与 Embedding 教程，可与长期记忆配合使用。

---

16. 自定义 Agent（从零继承 AgentBase）

当内置的 ReActAgent 不满足需求时，你可以从基类继承，完全自定义 Agent 的行为。两个基类：

基类	需实现的抽象方法	适用
AgentBase	reply、observe、handle_interrupt	任意自定义 Agent
ReActAgentBase	上面三个 + _reasoning、_acting	想自定义"推理"和"行动"两阶段

一个最简自定义 Agent（直接调模型，不带工具循环）：

from agentscope.agent import AgentBase
from agentscope.message import Msg
from agentscope.model import DashScopeChatModel
from agentscope.formatter import DashScopeChatFormatter
from agentscope.memory import InMemoryMemory
import os

class MyAgent(AgentBase):
    def __init__(self) -> None:
        super().__init__()
        self.name = "Friday"
        self.sys_prompt = "你是助手 Friday。"
        self.model = DashScopeChatModel(
            model_name="qwen-max",
            api_key=os.environ["DASHSCOPE_API_KEY"],
            stream=False,
        )
        self.formatter = DashScopeChatFormatter()
        self.memory = InMemoryMemory()

    async def reply(self, msg):
        await self.memory.add(msg)
        prompt = await self.formatter.format([
            Msg("system", self.sys_prompt, "system"),
            *await self.memory.get_memory(),
        ])
        response = await self.model(prompt)
        out = Msg(name=self.name, content=response.content, role="assistant")
        await self.memory.add(out)
        await self.print(out)   # 输出到控制台/前端
        return out

    async def observe(self, msg):
        # 只"听"，不回复（用于接收广播消息）
        await self.memory.add(msg)

    async def handle_interrupt(self):
        # 被用户打断时如何应对
        return Msg(self.name, "我被打断了，需要我做什么？", "assistant")

• reply：核心逻辑，收到消息、产出回复。
• observe：只接收不回复（在 MsgHub 里"旁听"别人发言）。
• handle_interrupt：实时中断时的处理（见第 18 节）。
• await self.print(msg)：把消息输出到控制台或前端（Studio）。

---

17. Hooks 与 Middleware

Hooks（钩子）

ReActAgent 允许你在关键函数前后挂钩子，做日志、监控、改写输入输出等。可挂钩的点包括 reply、observe、print、_reasoning、_acting 的前后。常用于：记录每一步推理、拦截敏感内容、统计 token、给前端推送中间状态。

Middleware（中间件）

中间件是 v1.0 引入的、用于控制工具执行的可组合机制（toolkit middleware）。你可以在工具被调用前后插入逻辑：权限校验、参数改写、结果脱敏、限流、审计等。多个中间件可以串联组合，是做"安全与治理"的关键手段。

经验：Hooks 偏"观察/旁路"，Middleware 偏"拦截/控制工具调用"。生产环境做合规和安全时，两者结合用。

---

18. 人机协同与实时中断

UserAgent：把"人"接入流程

UserAgent 代表真实用户，用来接收命令行 / Web UI 的输入，让人也成为多智能体流程的一环：

from agentscope.agent import UserAgent

user = UserAgent(name="用户")
user_msg = await user(None)   # 等待并获取用户输入

把 UserAgent 和普通 Agent 放进同一个对话循环，就实现了"人和 AI 轮流发言"的人机协同。

实时中断（Realtime Steering）

ReActAgent 支持在生成过程中被用户打断：对话可以随时取消，并借助稳健的记忆保存机制无缝恢复。这对长任务、语音交互至关重要——用户说"停，换个方向"，Agent 能立刻停下并接住新指令，而不是把已经跑了一半的任务全丢掉。自定义 Agent 通过实现 handle_interrupt 来定义被打断时的行为。

---

19. 状态与会话管理

把 Agent 的状态（记忆、计划等）保存下来、之后恢复，是做"可持久化对话"的基础。

# 导出状态
state = agent.state_dict()

# 之后恢复
agent.load_state_dict(state)

生产环境中，AgentScope 提供 Session（会话）抽象做状态持久化，支持 Redis 等后端，并支持多租户、多会话隔离——同一个服务为多个用户提供服务时，各自的记忆与状态互不干扰。这是从"demo"走向"线上服务"的必备能力，详见官方 State/Session Management 教程。

---

第四部分 · 精通与生产

20. AgentScope Studio：可视化、调试与 Tracing

AgentScope Studio 是配套的可视化开发工具，能把 Agent 的运行过程（消息流、工具调用、推理步骤）实时呈现在网页上，极大方便调试。

启动后，在代码里把运行接入 Studio，即可在浏览器看到完整的执行链路。配合 Tracing（基于 OpenTelemetry / OTel），你能拿到结构化的调用链、耗时、token 消耗，便于排查"为什么这一步调错了工具"“哪一步最慢”。

这套"可见、可追踪"的能力，正是 AgentScope 口号"agents you can see, understand and trust"（可见、可理解、可信任的智能体）的体现，也是它区别于很多框架的工程优势。

---

21. 评测 Evaluation

光能跑还不够，要知道"跑得好不好"。AgentScope 提供评测框架，可以系统化地评估 Agent 在一组任务上的表现，支持：

• 自定义评测任务集与指标。
• 配套 OpenJudge（统一评测与质量奖励框架），做"以模型为裁判"的整体性评测。
• 评测结果可存储、可复现，便于做版本对比和回归测试。

在你迭代 prompt、换模型、改工具时，用评测来量化每次改动的好坏，而不是凭感觉。

---

22. 部署与服务化（Runtime / AgentApp）

把 Agent 变成一个可被调用的在线服务，核心是 AgentApp（早期在独立的 agentscope-runtime 包，现已并入 AgentScope）。它基于 FastAPI，提供 “Agent as API” 的能力。

一个最小服务化示例（要点版）：

import os
from contextlib import asynccontextmanager
from fastapi import FastAPI
from agentscope.agent import ReActAgent
from agentscope.model import DashScopeChatModel
from agentscope.formatter import DashScopeChatFormatter
from agentscope.tool import Toolkit, execute_python_code
from agentscope.memory import InMemoryMemory
from agentscope_runtime.engine import AgentApp
from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 启动时初始化资源（会话存储等）
    yield
    # 关闭时清理资源

agent_app = AgentApp(
    app_name="Friday",
    app_description="一个在线助手",
    lifespan=lifespan,
)

@agent_app.query(framework="agentscope")
async def query_func(self, msgs, request: AgentRequest = None, **kwargs):
    toolkit = Toolkit()
    toolkit.register_tool_function(execute_python_code)
    agent = ReActAgent(
        name="Friday",
        model=DashScopeChatModel("qwen-turbo", api_key=os.getenv("DASHSCOPE_API_KEY"), stream=True),
        sys_prompt="你是助手 Friday。",
        toolkit=toolkit,
        memory=InMemoryMemory(),
        formatter=DashScopeChatFormatter(),
    )
    # 流式返回（处理 request.session_id / request.user_id 做会话隔离）
    ...

部署形态：

• 本地：直接 uvicorn 跑。
• Serverless：部署到云函数 / 容器。
• K8s：内置 OTel 可观测性，适合集群化、弹性伸缩。

它还提供安全沙箱（本地 / Docker / E2B 后端）来隔离运行工具和代码，以及多租户、多会话隔离、分布式中断服务等生产特性。

---

23. A2A：跨框架多智能体协作

A2A（Agent-to-Agent） 是让不同服务、甚至不同框架的智能体互相发现、互相调用的标准协议。AgentScope 内置 A2A 支持：你可以把一个 Agent 注册成可被发现的服务（配合 Nacos 等注册中心），其他 Agent 像调用微服务一样调用它。

这让你能构建分布式多智能体系统：不同团队用不同技术栈实现的 Agent，通过 A2A 协同完成一个大任务。配合第 13 节的 MCP（接工具）和这里的 A2A（接 Agent），AgentScope 的"互联互通"能力就完整了。

---

24. 模型微调与 Agentic RL（Tuner）

当通用模型在你的特定任务上不够好时，可以微调。AgentScope 提供 Tuner 模块，并支持强化学习（RL）工作流来调优 Agent，提升其在复杂任务上的表现。配套的 Trinity-RFT 是一个通用、灵活、可扩展的大模型强化微调（Reinforcement Fine-Tuning）框架。

典型用途：用真实/合成的任务轨迹做 agentic RL，让 Agent 在工具使用、多步推理上越来越熟练。这属于"精通"阶段的进阶能力，需要一定的训练资源和数据准备，详见官方 Tuner 教程。

---

25. 实时语音 Agent

AgentScope 支持实时语音交互：Agent 能听懂语音输入、用语音回应，并支持多智能体语音对话（官方甚至做了"狼人杀"语音游戏 demo）。实时语音 Agent 支持打断处理——你说话时可以打断它，它能立刻停下来听你说。

相关组件包括实时模型（如 OpenAIRealtimeModel、GeminiRealtimeModel）和 TTS（文本转语音，支持如 DashScope CosyVoice 等）。这让你能做出"打电话一样"自然的语音助手。具体见官方 Realtime Agent 与 TTS 教程。

---

26. AgentScope 2.0 变化与迁移

本教程主体基于 v1.0 稳定版（文档站默认版本）。主干代码正在向 2.0 演进，2.0 把原 agentscope-runtime 的能力（工具沙箱、Agent-as-a-Service API、全栈可观测性）原生整合了进来，并引入了一些新抽象。你在最新 README 里可能会看到这样的写法：

# 2.0 风格（与 1.0 有差异，注意区分）
from agentscope.agent import Agent
from agentscope.tool import Toolkit, Bash, Grep, Glob, Read, Write, Edit
from agentscope.credential import DashScopeCredential
from agentscope.model import DashScopeChatModel
from agentscope.message import UserMsg
from agentscope.event import EventType

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()]),
)

async for evt in agent.reply_stream(UserMsg("Tony", "Hi, Friday!")):
    match evt.type:
        case EventType.REPLY_START: ...
        case EventType.MODEL_CALL_START: ...
        case EventType.TEXT_BLOCK_START: ...

主要差异（便于你识别版本）：

• 类名 ReActAgent → 通用 Agent；参数 sys_prompt → system_prompt。
• 凭证从直接传 api_key → 用 DashScopeCredential 等 Credential 对象。
• 新增统一事件系统（reply_stream + EventType 事件总线），更适合驱动前端 UI 和人机协同。
• 新增权限系统（对工具与资源的细粒度控制）、工作区/沙箱、可扩展中间件、多租户多会话服务等生产特性。

迁移建议：

• 新项目若追求稳定，先用 v1.0 文档与 API；
• 关注 GitHub Releases / CHANGELOG 的迁移指南再升级 2.0；
• 因为框架更新很快，写代码前务必以你安装版本对应的官方文档为准（用 pip show agentscope 看版本，文档站可切换 Stable / 版本号）。

---

27. 学习路径与资源

推荐学习路径

1. 入门（1-2 天）：跑通第 4 节 Hello World → 理解 Msg / Model / Formatter / Memory / Toolkit 五件套（第 5-9 节）。
2. 单 Agent 精通（2-3 天）：吃透 ReActAgent 参数（第 10 节）、结构化输出（第 11 节）、自定义工具（第 9 节）、自定义 Agent（第 16 节）。
3. 多智能体（3-5 天）：MsgHub、Pipeline、路由、Handoff、辩论（第 12 节），再加 MCP（第 13 节）。
4. 工程化（1 周+）：Plan、RAG、Hooks/Middleware、状态会话（第 14-19 节），Studio 调试（第 20 节）。
5. 生产与精通：评测、部署服务化、A2A、微调、实时语音（第 21-25 节）。

关键资源

• 官方文档（最权威，注意切版本）：https://doc.agentscope.io
• GitHub 主仓库：https://github.com/agentscope-ai/agentscope
• 示例与模板集合：AgentScope-Samples（仓库内）
• Java 版本：https://github.com/agentscope-ai/agentscope-java
• 论文：AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications（arXiv:2508.16279）、AgentScope: A Flexible yet Robust Multi-Agent Platform（arXiv:2402.14034）

几条实战经验

• 模型与 Formatter 永远成对，换模型记得一起换。
• 多发言者场景一律用 MultiAgentFormatter，否则模型分不清谁说的。
• 结构化输出读 msg.metadata，不要去 content 里正则抠 JSON。
• MsgHub 的"进/出"决定信息可见范围，用它来精确控制谁能听见谁。
• 生产环境一定上 Studio + Tracing + Middleware，可观测和可控制是上线的前提。
• 框架更新极快，遇到 API 对不上，先看你本地版本对应的官方文档，再看 Releases。

---

祝你玩转 AgentScope。从一个会跑 Hello World 的小助手，到一套可观测、可中断、能协作、能上线的多智能体系统，路径就在上面——动手把每一节的代码跑一遍，是最快的精通方式。