Appearance
Agent Team 🔥
Agent Team 是 AgentScope 2.x 在 Agent Service 部署层提供的多 Agent 协作能力。一个 Leader 会话（用户直接对话的 session）可以按需创建 Worker 会话、与之交换消息，并在任务完成后解散团队。 整个协作故事不是通过一套独立的编排框架，而是通过 五个内置 team tools 表达--Leader 像调用普通 工具一样创建团队、派发任务、收集结果。这是 2.x 多 Agent 协作的唯一官方方案：SDK 层没有 Pipeline / Workflow / MsgHub / routing / handoff 等原语（那些是 1.x 的概念，2.x 已移除）。
版本基线：本文以 Python
agentscope 2.0.4（PyPI，2026-07-07）为准，要求 Python>=3.11。 Agent Team 是部署层特性，依赖 Agent Service（create_app+ Redis + message bus + workspace manager）。导入路径为from agentscope.app import create_app, SubAgentTemplate（源：src/agentscope/app/__init__.py）。Agent Team 在2.0.1引入，2.0.4新增AgentInvite（邀请已有 Agent 加入团队）。2.x 文档站存在版本化陷阱：非版本化的/en/URL 会 404，本页所有 官方链接均使用versions/2.0.4/en/形式。
为什么需要 Agent Team
单个 Agent 能自主完成"推理 -> 调用工具 -> 回灌结果 -> 继续推理"的闭环，但很多现实任务需要多个 分工的 Agent 并行协作：一个负责探索代码库，一个负责编写代码，一个负责审查。把它们塞进同一个 Agent 的上下文会让 ReAct 循环臃肿且难以并发；而让应用代码手工编排多个 Agent 实例的消息传递又 容易写出脆弱的胶水逻辑。
Agent Team 把这个协作模式做进了部署层：Leader 自动决定何时创建团队、创建几个 Worker、各自分配 什么任务，然后通过消息总线与 Worker 通信。Worker 各自拥有独立的 session、独立的上下文与独立的 事件流，天然并发，互不阻塞。
2.x 多 Agent 的唯一方案
2.x 的 SDK 层（agentscope.agent.Agent、Toolkit、Permission 等）是单 Agent抽象--它没有 Pipeline、MsgHub、Workflow、routing、handoff 等多 Agent 编排原语。这些概念在 1.x 中存在，但在 2.0 的破坏性重构中被移除。如果你在 2.x 中需要多 Agent 协作，正确且唯一的官方路径是 Agent Team。 不要在 SDK 层寻找 1.x 的 Pipeline / MsgHub，它们不存在。
前端类比
如果你来自前端，可以把 Agent Team 类比为 主线程派发 Web Worker 或 microservice orchestrator：
- Leader 像主线程：接收用户请求，把可并行的子任务派发给多个 Worker，自己不亲自执行重活，而是 汇总 Worker 的结果。
- Worker 像 Web Worker：在独立线程（独立 session）中运行，有自己的状态与事件流，通过
postMessage等价的TeamSay与 Leader 通信。 - 消息总线 像
MessageChannel/ 消息队列：Leader 和 Worker 可以在不同进程甚至不同节点上， 通信全部经过 Redis 消息总线中转，发送方写收件方 inbox，接收方被 wakeup 唤醒后处理。
AgentScope 原生语义：Agent Team 不是 Web Worker 的线程模型，也不是 microservice 的 RPC 模型。每个 Worker 是一个完整的 Agent Service session--拥有自己的 AgentState、上下文、权限上下文 与 ReAct 循环。通信是异步消息传递（inbox + wakeup），不是同步 RPC。Leader 不"调用"Worker 的方法，而是向其 inbox 推入一条 HintBlock 消息，Worker 被唤醒后在下一轮推理前由 InboxMiddleware 排空 inbox。这意味着 Worker 的执行与 Leader 完全解耦，两者可以同时运行。
Leader-Worker 通信流程
下面这张时序图说明一次完整的团队协作：用户向 Leader 发送任务，Leader 调用内置 team tools 创建 团队、生成 Worker、派发任务，Worker 并发执行后通过 TeamSay 回报结果，Leader 汇总后回复用户。 图前先说明：Leader 与 Worker 是不同的 session，所有跨 session 通信都经过 Redis 消息总线， Worker 一经创建就立即在自己的 session 中并发执行，不是 Leader 的嵌套协程。
图后解释关键阶段：
- 创建团队：Leader 调用
TeamCreate，以当前 session 为根建立一个TeamRecord，自己成为 Leader。只有 Leader 能增删成员或解散团队。 - 生成 Worker：Leader 调用
AgentCreate，指定 Worker 名称、角色描述与首个任务。Worker 一经 创建就立即开始执行，不需要额外的启动信号。Leader 也可以用AgentInvite邀请一个已有 Agent 加入团队（2.0.4 新增）。 - 消息投递：所有跨成员通信都经消息总线中转。发送方的工具调用（
TeamSay、AgentCreate的 初始任务等）把一个HintBlock推入接收方的 inbox，同时为接收方 enqueue 一个 wakeup。集群中任意 进程上的 wakeup dispatcher 都可以认领这个 wakeup 并驱动对应 session。 - 并发执行：Worker 在各自独立的 session 中运行 ReAct 循环，彼此不阻塞、不嵌套。Leader 通过 读取 Worker 的 session 事件流或等待 Worker
TeamSay回报来观察进度。 - 回报与汇总：Worker 完成任务后用
TeamSay向 Leader 发送结果。Leader 被 wakeup 唤醒后，InboxMiddleware在下一轮推理前排空 inbox，团队消息以HintBlockEvent形式进入 Leader 上下文， Leader 据此汇总并回复用户。
构造带团队的 Agent Service
Agent Team 内置于 Agent Service，无需额外配置。只要用 create_app 启动了带 Redis 存储、消息总线 与 workspace manager 的服务，Leader 就自动拥有全部 team tools。下面是一个完整构造示例，注册了 一个自定义 explorer 子 Agent 模板（只读权限），凭据通过环境变量注入：
python
import os
from agentscope.app import create_app, SubAgentTemplate
from agentscope.app.storage import RedisStorage
from agentscope.app.message_bus import RedisMessageBus
from agentscope.app.workspace_manager import LocalWorkspaceManager
from agentscope.permission import PermissionContext, PermissionMode
# Redis 连接信息从环境变量读取，不要写死在代码里
storage = RedisStorage(host=os.environ["REDIS_HOST"], port=6379)
message_bus = RedisMessageBus(host=os.environ["REDIS_HOST"], port=6379)
workspace_manager = LocalWorkspaceManager()
app = create_app(
storage=storage,
message_bus=message_bus,
workspace_manager=workspace_manager,
sub_agent_templates=[
SubAgentTemplate(
type="explorer",
description=(
"Read-only agents specialized in exploration tasks. "
"Use this type when you need to investigate the "
"codebase without making any changes."
),
system_prompt_template=(
"You are {member_name}, an explorer "
"agent in team '{team_name}' led by {leader_name}.\n\n"
"Team purpose: {team_description}\n\n"
"Your role: {member_description}\n\n"
"## Responsibilities\n"
"- Complete the exploration tasks assigned by the team leader.\n"
"- You are read-only: you may inspect files and the codebase, but "
"you must never modify, create, or delete anything.\n\n"
"## Reporting\n"
"- Always report the task result back to {leader_name} using the "
"TeamSay tool, whether the task succeeds or fails."
),
permission_context=PermissionContext(
mode=PermissionMode.EXPLORE,
),
),
],
)上面的配置含义：服务启动后，Leader 创建 Worker 时可以选择 explorer 类型，该 Worker 的系统提示词 由 system_prompt_template 渲染（占位符在创建时填充），权限模式为只读 EXPLORE。Leader 的 chat model 与 workspace 绑定会被 Worker 继承，但 Worker 的权限上下文由其 SubAgentTemplate 的 permission_context 决定。
⚠️ Agent Team 是部署层特性。如果你没有用
create_app启动 Agent Service（只在 SDK 层 直接构造Agent实例），则不存在 team tools，也无法使用 Agent Team。先完成 部署 Agent Service 再回到本页。
内置 team tools
Leader session 自动获得以下工具；Worker 只能看到 TeamSay。
| 工具 | 谁拥有 | 作用 |
|---|---|---|
TeamCreate | Leader | 以当前 session 为根创建新团队，自己成为 Leader |
AgentCreate | Leader | 在团队中生成新 Worker，指定名称、角色描述、首个任务与权限模式；Worker 创建后立即执行 |
TeamSay | Leader + Worker | 向指定成员发送消息（或广播），接收方通过 inbox 收取并在下次 wakeup 时恢复 |
TeamDelete | Leader | 解散团队并清理所有成员 session；只有 Leader 能调用 |
AgentInvite | Leader | 邀请一个已有 Agent 加入团队（2.0.4 新增），被邀请者会创建新 session |
几个要点：
- Worker 的工具集：Worker 只拥有
TeamSay，不能创建子团队、不能创建其他 Worker、不能解散团队。 这保证了协作拓扑是星形的--Leader 是唯一的编排中心。 AgentCreate的subagent_type：当没有注册自定义模板时，AgentCreate不暴露subagent_type参数，所有 Worker 使用内置默认模板。注册了自定义模板后，AgentCreate自动增加subagent_type枚举字段（包含"default"与所有自定义类型），Leader 看到每种类型的description后自行选择。TeamDelete的清理范围：通过AgentCreate创建的 Worker 会被永久删除；通过AgentInvite邀请的 Agent 不受影响，只移除其与团队的关联关系。被邀请者有自己的 workspace 与 Agent 生命周期。- 邀请范围控制：创建或编辑 Agent 时可以设置
Invitable（是否允许被邀请加入团队）与Invite description（展示给 Leader 的邀请说明），控制哪些 Agent 可以被纳入团队。
SubAgentTemplate
SubAgentTemplate 是 Worker 的可复用蓝图，定义了 Leader 用 AgentCreate 生成 Worker 时的全部 默认配置。字段如下（源：官方 2.0.4 文档与 src/agentscope/app/_types.py）：
| 字段 | 必填 | 默认值 | 作用 |
|---|---|---|---|
type | 是 | - | 模板标识，如 "explorer"、"coder"，成为 AgentCreate 的 subagent_type 枚举值 |
description | 是 | - | Agent 可读描述，暴露在 AgentCreate 工具 schema 中，帮 Leader 选择合适类型 |
system_prompt_template | 是 | - | Worker 系统提示词的 Python format 字符串，支持占位符替换（见下表） |
permission_context | 否 | PermissionContext() | Worker 的权限上下文，控制 Worker 能做什么（如 PermissionMode.EXPLORE 只读） |
context_config | 否 | ContextConfig() | Worker 的上下文窗口配置 |
react_config | 否 | ReActConfig() | Worker 的 ReAct 循环配置 |
tasks_context | 否 | TaskContext() | 预定义任务上下文，允许模板播种初始工作流 |
系统提示词占位符
system_prompt_template 在 Worker 创建时用以下变量格式化：
| 占位符 | 值 |
|---|---|
{team_name} | TeamCreate 设定的团队名称 |
{team_description} | TeamCreate 设定的团队描述 |
{member_name} | AgentCreate 设定的 Worker 名称 |
{member_description} | AgentCreate 设定的 Worker 角色描述 |
{leader_name} | Leader Agent 的显示名称 |
运行时行为
- 未注册自定义模板：
AgentCreate不暴露subagent_type参数，所有 Worker 使用内置默认模板， 工具 schema 保持精简。 - 注册了自定义模板：
AgentCreate自动增加subagent_type枚举字段，列出所有可用类型（含"default"），Leader 看到每种类型的description后自行选择。 - 覆盖默认：注册
type="default"的模板会替换内置默认模板。 - 唯一性：模板类型名必须唯一，重复会导致启动时
ValueError。
权限继承
Worker 继承 Leader 的 chat model 与 workspace 绑定，但权限上下文由其 SubAgentTemplate 的 permission_context 决定。这意味着你可以为不同角色的 Worker 设置不同的权限边界：探索型 Worker 用 EXPLORE 只读模式，编码型 Worker 用 ACCEPT_EDITS 可写模式。如果未注册自定义模板，所有 Worker 使用内置默认权限上下文（PermissionContext()，即 DEFAULT 模式）。
通信机制：Redis 消息总线
Agent Team 为分布式部署设计。所有成员间通信都经 Redis 消息总线中转，Leader 与 Worker 可以 运行在不同进程或不同节点上，无需修改任何代码。通信复用了 Agent Service 用于定时触发与后台工具 完成的同一套 inbox + wakeup 原语：
- 发送方的工具调用（
TeamSay、AgentCreate的初始任务等）通过消息总线把一个HintBlock推入 接收方 session 的 inbox。 - 为接收方 enqueue 一个 wakeup。
- 集群中任意进程上的 wakeup dispatcher 认领该 wakeup，驱动对应 session 的
ChatService.run。 InboxMiddleware在下一轮推理前排空 inbox，排队的团队消息以HintBlockEvent形式进入接收方 上下文。
团队消息以 HintBlock 形式投递，外层包裹 <team-message from="..."> 标签，使接收方的 LLM 能 将其与普通用户消息区分开。这意味着 Worker 不需要特殊代码来"接收"团队消息--它就是上下文中的一条 提示块，ReAct 循环自然地读取并据此推理。
关键设计含义：Worker 是并发的，不是 Leader 的嵌套协程。Leader 不会被 Worker 的执行阻塞。 Leader 观察 Worker 进度的途径有两条：读取 Worker session 的事件流，或等待 Worker 用 TeamSay 回报。这也是 Agent Team 能随 Agent Service 一起横向扩展的原因--Worker 可以被集群中任意节点上的 dispatcher 驱动。
与 1.x 的区别
1.x 提供了 Pipeline、MsgHub 等多 Agent 编排原语，用于在 SDK 层串联或广播消息。2.0 的破坏性 重构移除了这些原语：SDK 层不再有 Pipeline、MsgHub、Workflow、routing 或 handoff。2.x 的多 Agent 协作统一收归到部署层的 Agent Team：
| 维度 | 1.x | 2.x |
|---|---|---|
| 多 Agent | Pipeline / MsgHub（SDK 层原语） | Agent Team（部署层，内置 team tools） |
| 编排方式 | 应用代码显式串联 / 广播 | Leader 自主决策创建团队与派发任务 |
| 通信 | 进程内消息传递 | Redis 消息总线（inbox + wakeup，可跨节点） |
| 并发 | 协程级 | session 级（独立 session，天然分布式） |
1.x 到 2.x 的完整迁移指南见 1.x 到 2.x 迁移。
⚠️ 1.x 仅作历史对照：1.x 的
Pipeline、MsgHub、ReActAgent、sys_prompt=在 2.x 全部移除，不能作为 2.x 代码使用。不要在 2.x SDK 层寻找这些原语。
常见错误
误以为 SDK 层有 Pipeline / MsgHub：2.x SDK 层没有 Pipeline、MsgHub、Workflow、routing 或 handoff。这些是 1.x 概念，2.x 已移除。多 Agent 协作的唯一官方方案是部署层的 Agent Team。
⚠️ 1.x 仅作历史对照：1.x 的
Pipeline/MsgHub在 2.x 全部移除，不能作为 2.x 代码 使用。迁移参见 1.x 到 2.x 迁移。未启动 Agent Service 就用 Team：Agent Team 是部署层特性，依赖
create_app启动的 Agent Service（Redis + message bus + workspace manager）。只在 SDK 层直接构造Agent实例不会有 team tools。先完成 部署 Agent Service。Worker 权限过宽：未注册自定义模板时，所有 Worker 使用内置默认权限上下文。如果你需要只读 探索型 Worker，必须注册
permission_context=PermissionContext(mode=PermissionMode.EXPLORE)的SubAgentTemplate，否则 Worker 可能在DEFAULT模式下频繁触发 HITL 确认，或在ACCEPT_EDITS下意外修改文件。根据角色选择合适的PermissionMode，详见 权限系统。误以为 Worker 是 Leader 的嵌套协程：Worker 在独立 session 中并发运行，不是 Leader 协程内 的子任务。Leader 不会被 Worker 阻塞，两者通过消息总线异步通信。如果你期望"调用 AgentCreate 后 同步等待 Worker 完成"，这是错误的心智模型--应该让 Worker 完成后用
TeamSay回报。system_prompt_template占位符写错：占位符是 Python format 字符串语法（{team_name}等）。 写成${team_name}或都不会正确替换。可用占位符见 系统提示词占位符 表。TeamDelete后期望被邀请 Agent 被清理：TeamDelete只永久删除通过AgentCreate创建的 Worker；通过AgentInvite邀请的 Agent 不受影响，只移除其与团队的关联。被邀请者保留自己的 workspace 与生命周期。
先修
- 部署 Agent Service - 理解
create_app、Redis 存储、消息总线 与 workspace manager，Agent Team 建立在此基础上
下一步
- 1.x 到 2.x 迁移 - 1.x 的 Pipeline / MsgHub 已移除， 迁移到 2.x Agent Team