> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能体团队

> Leader 智能体通过内置 team 工具派生并协调 worker 智能体

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

## 快速上手

随仓库附带的 [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) 后端默认启用了 team 工具，配套的 [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) 前端开箱即可渲染团队成员关系与各 worker 的事件流。按照[智能体服务快速上手](/versions/2.0.3/zh/deploy/agent-service#试用示例)启动两者 —— 跑起来后让 leader 智能体组建一个团队，你会看到它自动调用 `TeamCreate` / `AgentCreate`，观察 worker 上线，并在 UI 中看到它们互相交换消息。

<Frame caption="在示例 Web UI 中，leader 智能体组建团队并协调 worker。">
  <img src="https://mintcdn.com/agentscope-ai-786677c7/c8Op3M8_8-WXpeVH/images/team.gif?s=604f394f94cca0dbca8fdeee75a0f7ff" alt="智能体团队协作演示" width="1920" height="1080" data-path="images/team.gif" />
</Frame>

## 概念

| 概念                     | 说明                                                                                               |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| **团队（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`：

```python theme={null}
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 可调用。                            |

### 协调模型

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

团队通信复用了服务用于调度触发与后台工具完成的同一组 inbox + wakeup 原语：

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

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

## 延伸阅读

<CardGroup cols={2}>
  <Card title="智能体服务" icon="server" href="/versions/2.0.3/zh/deploy/agent-service">
    支撑团队的托管层 —— 会话、消息总线、工作区生命周期。
  </Card>

  <Card title="Agent" icon="robot" href="/versions/2.0.3/zh/building-blocks/agent">
    每个团队成员所运行的智能体抽象。
  </Card>
</CardGroup>