Agent Team

Agent Team is the multi-agent layer built on top of Agent Service. A leader agent — the session the user talks to — can spawn worker agents on demand and exchange messages with them, while every member is just another session with its own state, workspace binding, and event stream. The whole coordination story is expressed through four built-in tools rather than a separate orchestration framework.

Quickstart

The bundled examples/agent_service backend ships with the team tools enabled, and the matching examples/web_ui frontend renders team membership and per-worker streams out of the box. Follow the Agent Service quickstart to boot both — once they are running, ask the leader agent to assemble a team and you will see it call TeamCreate / AgentCreate automatically, watch workers come online, and observe them exchange messages in the UI.

Agent team coordination demo — A leader agent assembling a team and coordinating workers in the example web UI.

Concepts

Concept	Description
Team	A persistent group of agent members owned by one user. A `TeamRecord` carries the team’s identity (name, description) and its member list.
Leader	The session that created the team. Only the leader can add or remove members or end the team.
Worker	A session spawned as a team member. Workers run their own ReAct loop in their own session and inherit the leader’s chat model + workspace context.
Team message	A message routed between members through the message bus. Delivered as a `HintBlock` wrapped in a `<team-message from="…">` tag so the recipient’s LLM can disambiguate it from a regular user turn.

Usage

Create a team

The team feature is built into Agent Service — no extra configuration is required. When a user sends a task that benefits from multi-agent collaboration, the leader agent automatically uses the built-in team tools to assemble and coordinate a team of workers. Out of the box, the leader agent can:

Create a team with a name and description that frames the collaboration goal.
Spawn workers by giving each a name, role description, and an initial task. Workers begin executing immediately upon creation.
Invite existing agents to join the team, coordinate and communicate with them.
Exchange messages with workers to provide follow-up instructions or collect results.
Dissolve the team when the task is complete, cleaning up all worker sessions.

Every worker runs concurrently in its own session with its own event stream, visible in the frontend UI alongside the leader’s conversation. The leader orchestrates work by reading worker outputs and sending messages — all through the same chat interface. By default, all workers share the same system prompt template and permission settings. To give different worker roles different capabilities — for example, a read-only explorer versus a full-access coder — register custom sub-agent templates as described in the next section. Note the invited agents have their own workspace and agent lifecycle, which won’t be affected when the team is dissolved.

Custom sub-agent types

By default, every worker spawned by AgentCreate uses the same built-in system prompt and permission context. In practice, different roles need different capability boundaries — an agent that only explores the codebase should not be able to modify files, while one that writes code needs full edit access. SubAgentTemplate solves this by letting you define reusable blueprints that the leader agent can choose from when creating workers.

Registering templates

Pass a list of SubAgentTemplate instances to create_app via the sub_agent_templates parameter:

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=(
                "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}.

Team purpose: {team_description}

Your role: {member_description}

## Responsibilities
- Complete the exploration tasks assigned by the team leader.
- You are read-only: you may inspect files and the codebase, but \
you must never modify, create, or delete anything.

## Reporting
- 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,
            ),
        ),
    ],
)

Template fields

Field	Required	Default	Description
`type`	Yes	—	Template identifier (e.g. `"explorer"`, `"coder"`). Becomes an enum value of the `subagent_type` parameter in `AgentCreate`.
`description`	Yes	—	Agent-readable description exposed in the `AgentCreate` tool schema so the leader can choose the appropriate type.
`system_prompt_template`	Yes	—	Python format string for the worker’s system prompt. See available placeholders below.
`permission_context`	No	`PermissionContext()`	Permission context applied to the worker. Controls what the worker is allowed to do (e.g. `PermissionMode.EXPLORE` for read-only).
`context_config`	No	`ContextConfig()`	Context window configuration for the worker.
`react_config`	No	`ReActConfig()`	ReAct loop configuration for the worker.
`tasks_context`	No	`TaskContext()`	Pre-defined task context, allowing the template to seed an initial workflow.

System prompt placeholders

The system_prompt_template string is formatted with these variables when a worker is created:

Placeholder	Value
`{team_name}`	The team’s name as set by `TeamCreate`.
`{team_description}`	The team’s description as set by `TeamCreate`.
`{member_name}`	The worker’s name as set by `AgentCreate`.
`{member_description}`	The worker’s role description as set by `AgentCreate`.
`{leader_name}`	The leader agent’s display name.

Runtime behavior

No custom templates registered — AgentCreate does not expose a subagent_type parameter at all. All workers use the built-in default template. This keeps the tool schema clean when templates are not needed.
Custom templates registered — AgentCreate automatically gains a subagent_type enum field listing all available types (including "default"). The leader agent sees each type’s description and can choose which one to use.
Overriding the default — registering a template with type="default" replaces the built-in default template entirely.
Uniqueness — template type names must be unique. Duplicate types cause a ValueError at startup.

Set invitation scope

When creating/editing an agent, you can set if the agent can be invited to join a team by setting the Invitable and Invite description fields.

Invitable: If the other agents can invite this agent to join a team.
Invite description: The description of the agent that will be shown to the leader when inviting this agent to join a team.

Architecture

Built-in tools

A leader session is automatically given these tools. Workers see only TeamSay.

Tool	Purpose
`TeamCreate`	Create a new team rooted at the current session and become its leader.
`AgentCreate`	Spawn a new worker into the team with a name, role description, first task, and permission mode. The worker begins executing as soon as it is created.
`TeamSay`	Send a message to a named member (or broadcast). The recipient’s session receives the message through its inbox and resumes on the next wakeup.
`TeamDelete`	Dissolve the team and clean up every member session. Only the leader can call this.
`AgentInvite`	Invite an existing agent to join the team. A new session will be created for the invited agent.

When deleting a team, agents created within the team (via AgentCreate) will be permanently deleted, while invited agents (via AgentInvite) will not be affected — only their association with the team will be removed.

Coordination model

Agent Team is designed for distributed deployments by default. All inter-member communication is mediated by the message bus — a Redis-backed abstraction — so leader and worker sessions can live in different processes or different nodes without any code change. The sender writes to the recipient’s inbox; any wakeup dispatcher in the cluster can then claim the wakeup signal and drive that session on its own process. This is the same mechanism that powers scheduled fires and background-tool completions, which is why the team feature scales out the same way the rest of the service does. Team communication reuses the same inbox + wakeup primitives the service uses for scheduled fires and background-tool completions:

The sender’s tool call (TeamSay, AgentCreate’s initial prompt, …) pushes a HintBlock onto the recipient session’s inbox via the message bus.
A wakeup is enqueued for the recipient.
The wakeup dispatcher running on any process picks up the wakeup and drives ChatService.run for that session.
InboxMiddleware drains the inbox before the next reasoning step, so the queued team messages land in the recipient’s context as HintBlockEvents.

This means workers run concurrently on the same service — they are not nested coroutines under the leader. The leader observes a worker’s progress by reading its session stream, or by having the worker TeamSay back to it.

Agent Service

The hosting layer that powers teams — sessions, message bus, workspace lifecycle.

Agent

The agent abstraction each team member runs.

Get Started

Building Blocks

Agent as Service

Others

Quickstart

Concepts

Usage

Create a team

Custom sub-agent types

Registering templates

Template fields

System prompt placeholders

Runtime behavior

Set invitation scope

Architecture

Built-in tools

Coordination model

See also

Agent Service

Agent

​Quickstart

​Concepts

​Usage

​Create a team

​Custom sub-agent types

​Registering templates

​Template fields

​System prompt placeholders

​Runtime behavior

​Set invitation scope

​Architecture

​Built-in tools

​Coordination model

​See also

Agent Service

Agent

Quickstart

Concepts

Usage

Create a team

Custom sub-agent types

Registering templates

Template fields

System prompt placeholders

Runtime behavior

Set invitation scope

Architecture

Built-in tools

Coordination model

See also