智能体团队 - AgentScope

智能体团队（Agent Team）是构建在智能体服务之上的多智能体层。Leader 智能体 —— 即用户对话的那个会话 —— 可以按需派生 worker 智能体并与之交换消息，而每个成员都只是另一个拥有独立状态、工作区绑定与事件流的会话。整套协调能力通过四个内置工具表达，而非借助一套独立的编排框架。

快速上手

随仓库附带的 examples/agent_service 后端默认启用了 team 工具，配套的 examples/web_ui 前端开箱即可渲染团队成员关系与各 worker 的事件流。按照智能体服务快速上手启动两者 —— 跑起来后让 leader 智能体组建一个团队，你会看到它自动调用 TeamCreate / AgentCreate，观察 worker 上线，并在 UI 中看到它们互相交换消息。

概念

概念	说明
团队（Team）	由单个用户拥有的一组持久化智能体成员。`TeamRecord` 承载团队身份（名称、描述）及其成员列表。
Leader	创建团队的会话。只有 leader 可以添加 / 移除成员或解散团队。
Worker	作为团队成员被派生出的会话。Worker 在自己的会话中运行自己的 ReAct 循环，并继承 leader 的聊天模型 + 工作区上下文。
团队消息（Team Message）	通过消息总线在成员之间路由的消息。以 `HintBlock` 形式投递，外层包裹 `<team-message from="…">` 标签，让接收方的 LLM 能将其与普通的用户对话轮区分开。

使用

组建团队

团队功能是智能体服务的内置能力 —— 无需额外配置。当用户发送一个适合多智能体协作的任务时，leader 智能体会自动使用内置的 team 工具来组建并协调一支 worker 团队。开箱即用的能力包括：

创建团队 —— 通过名称与描述框定协作目标。
派生 worker —— 为每个 worker 指定名称、角色描述与首个任务。Worker 创建后立即开始执行。
交换消息 —— 与 worker 互发消息，下发后续指令或收集结果。
解散团队 —— 任务完成后清理所有 worker 会话。

每个 worker 在自己的会话里并发运行，拥有独立的事件流，可与 leader 的对话一起在前端 UI 中观察。Leader 通过阅读 worker 的输出并发送消息来组织工作 —— 一切都在同一个对话界面中完成。默认情况下，所有 worker 共用同一份系统提示词模板与权限设置。如果需要为不同角色赋予不同的能力边界 —— 例如只读的 explorer 与可写代码的 coder —— 可以按下一节所述注册自定义子智能体模板。

自定义子智能体类型

默认情况下，AgentCreate 派生的每个 worker 都使用相同的内置系统提示词和权限上下文。但在实际场景中，不同角色需要不同的能力边界 —— 只负责探索代码库的智能体不应能修改文件，而负责编写代码的智能体需要完整的编辑权限。SubAgentTemplate 正是为此而生：它允许你定义可复用的蓝图，leader 智能体在创建 worker 时可以从中选择。

注册模板

将一组 SubAgentTemplate 实例通过 sub_agent_templates 参数传给 create_app：

from agentscope.app import create_app, SubAgentTemplate
from agentscope.permission import PermissionContext, PermissionMode

app = create_app(
    storage=storage,
    message_bus=message_bus,
    workspace_manager=workspace_manager,
    sub_agent_templates=[
        SubAgentTemplate(
            type="explorer",
            description=(
                "专门从事探索任务的只读智能体。当你需要调查代码库"
                "但不做任何修改时，使用此类型。"
            ),
            system_prompt_template="""你是 {member_name}，由 {leader_name} \
领导的团队 '{team_name}' 中的 explorer 智能体。

团队目标：{team_description}

你的角色：{member_description}

## 职责
- 完成团队 leader 下达的探索任务。
- 你是只读的：可以检查文件和代码库，但绝不能修改、创建或删除任何内容。

## 汇报
- 无论任务成功或失败，都要使用 TeamSay 工具向 {leader_name} 汇报任务结果。""",
            permission_context=PermissionContext(
                mode=PermissionMode.EXPLORE,
            ),
        ),
    ],
)

模板字段

字段	必填	默认值	说明
`type`	是	—	模板标识符（例如 `"explorer"`、`"coder"`）。成为 `AgentCreate` 的 `subagent_type` 参数的枚举值。
`description`	是	—	暴露在 `AgentCreate` 工具 schema 中的、面向智能体可读的描述，帮助 leader 选择合适的类型。
`system_prompt_template`	是	—	Worker 系统提示词的 Python 格式化字符串。可用占位符见下文的系统提示词占位符。
`permission_context`	否	`PermissionContext()`	应用到 worker 的权限上下文。控制 worker 被允许做什么（例如 `PermissionMode.EXPLORE` 代表只读）。
`context_config`	否	`ContextConfig()`	Worker 的上下文窗口配置。
`react_config`	否	`ReActConfig()`	Worker 的 ReAct 循环配置。
`tasks_context`	否	`TaskContext()`	预置的任务上下文，允许模板预设初始工作流。

系统提示词占位符

创建 worker 时，system_prompt_template 字符串会用以下变量进行格式化：

占位符	取值
`{team_name}`	`TeamCreate` 设定的团队名称。
`{team_description}`	`TeamCreate` 设定的团队描述。
`{member_name}`	`AgentCreate` 设定的 worker 名称。
`{member_description}`	`AgentCreate` 设定的 worker 角色描述。
`{leader_name}`	Leader 智能体的展示名称。

运行时行为

未注册自定义模板 —— AgentCreate 完全不暴露 subagent_type 参数，所有 worker 都使用内置的默认模板。这能在不需要模板时保持工具 schema 整洁。
注册了自定义模板 —— AgentCreate 自动新增一个 subagent_type 枚举字段，列出所有可用类型（包括 "default"）。Leader 智能体能看到每种类型的描述并选择使用哪一种。
覆盖默认模板 —— 注册一个 type="default" 的模板会完全替换内置的默认模板。
唯一性 —— 模板的 type 名称必须唯一。重复的 type 会在启动时抛出 ValueError。

实现原理

内置工具

Leader 会话自动获得下列工具。Worker 只能看到 TeamSay。

工具	用途
`TeamCreate`	以当前会话为根创建一个新团队，并成为其 leader。
`AgentCreate`	向团队中派生一个新的 worker，附带名称、角色描述、首个任务与权限模式。Worker 创建后立即开始执行。
`TeamSay`	向指定成员发送消息（或广播）。接收方会话通过其收件箱接收消息，并在下一次唤醒时恢复运行。
`TeamDelete`	解散团队并清理所有成员会话。只有 leader 可调用。

协调模型

智能体团队天然为分布式部署而设计。所有成员间的通信都由消息总线居中转发 —— 一个由 Redis 支撑的抽象 —— 因此 leader 与 worker 会话可以位于不同进程或不同节点，无需任何代码改动。发送方将消息写入接收方的收件箱；集群中任意 wakeup dispatcher 都可以认领该唤醒信号，并在自己的进程上驱动该会话运行。这与支撑调度触发、后台工具完成的机制是同一套，也是为什么团队功能能与服务的其他部分一样横向扩展。团队通信复用了服务用于调度触发与后台工具完成的同一组 inbox + wakeup 原语：

发送方的工具调用（TeamSay、AgentCreate 的初始提示等）通过消息总线把 HintBlock 推到接收方会话的收件箱。
为接收方入队一个唤醒信号。
任意进程上运行的 wakeup dispatcher 取走该唤醒，并为该会话驱动 ChatService.run。
InboxMiddleware 在下一次推理步骤前清空收件箱，因此排队的团队消息会以 HintBlockEvent 的形式落入接收方上下文。

这意味着 worker 在同一服务中并发运行 —— 它们不是嵌套在 leader 之下的协程。Leader 通过读取 worker 的会话事件流，或让 worker TeamSay 回报，来观察其进展。

智能体服务

支撑团队的托管层 —— 会话、消息总线、工作区生命周期。

Agent

每个团队成员所运行的智能体抽象。

​快速上手

​概念

​使用

​组建团队

​自定义子智能体类型

​注册模板

​模板字段

​系统提示词占位符

​运行时行为

​实现原理

​内置工具

​协调模型

​延伸阅读