Multi-agent orchestration in AgentScope follows a Leader-Worker pattern. A leader agent (typically the one the user interacts with directly) can dynamically form a team, spawn specialized worker agents, delegate tasks, and collect reports. This system is built on a set of specialized tools, a template-based worker configuration system, and a cross-session projection mechanism that surfaces worker Human-In-The-Loop (HITL) requests to the leader's UI.
The orchestration is governed by framework-builtin tools: AgentCreate, AgentInvite, and TeamSay. These tools interact directly with the StorageBase and MessageBus to manage session state and inter-agent communication src/agentscope/app/_service/_chat.py91-103 src/agentscope/app/_lifespan.py140-154
AgentCreate: Spawns a brand-new worker agent. The worker is assigned a source='team' attribute and is automatically joined to the leader's team. It utilizes a SubAgentTemplate for its initial configuration src/agentscope/app/_types.py89-102AgentInvite: Borrows an existing user-owned agent into the team. Unlike AgentCreate, it mints a fresh team-scoped SessionRecord on top of an existing AgentRecord, preserving the agent's global state and workspace while allowing it to participate in the team conversation.TeamSay: The primary communication tool. It delivers messages to the target agent's inbox and triggers a wake-up via the MessageBus src/agentscope/app/_bus_ops.py163-204Communication between members is strictly routed through the TeamSay tool. It provides role-specific instructions:
| Natural Language Concept | Code Entity / Class | File Reference |
|---|---|---|
| Team Leader | Agent with team_id in SessionRecord | src/agentscope/app/_service/_chat.py31 |
| Spawn Worker | AgentCreate tool | src/agentscope/app/_tool/_agent_create.py |
| Invite Existing Agent | AgentInvite tool | src/agentscope/app/_tool/_agent_invite.py |
| Worker Template | SubAgentTemplate | src/agentscope/app/_types.py89 |
| Report Results | TeamSay tool | src/agentscope/app/_tool/_team_say.py |
| Team Registry | TeamRecord in StorageBase | src/agentscope/app/storage/_base.py |
Sources: src/agentscope/app/_service/_chat.py89-154 src/agentscope/app/_types.py89-185 src/agentscope/app/_bus_ops.py163-204
SubAgentTemplate defines the blueprint for workers created via AgentCreate. Templates allow developers to define specialized roles (e.g., "researcher", "coder") with specific system prompts and permission postures src/agentscope/app/_types.py89-104
Templates support fine-grained control over how workers inherit state from the leader:
system_prompt_template: A format string accepting placeholders like {team_name}, {leader_name}, and {member_description} src/agentscope/app/_types.py123-129override_leader_mode: If True, the worker uses the template's PermissionMode (e.g., EXPLORE for read-only workers). If False, it inherits the leader's current mode src/agentscope/app/_types.py151-161extend_leader_permission_rules: Merges leader-confirmed rules into the worker, preventing redundant HITL prompts for the user src/agentscope/app/_types.py163-175extend_leader_working_directories: Merges working directories (like AdditionalWorkingDirectory) from the leader to the worker src/agentscope/app/_types.py177-185Templates are registered during application startup via create_app src/agentscope/app/_app.py97 and stored in the ChatService src/agentscope/app/_service/_chat.py100 When AgentCreate is called, it routes to the appropriate template based on the subagent_type parameter src/agentscope/app/_service/_chat.py150-153
Sources: src/agentscope/app/_types.py89-185 src/agentscope/app/_app.py81-104 src/agentscope/app/_service/_chat.py90-154
Since workers run in background sessions, their Human-In-The-Loop (HITL) requests (e.g., tool execution confirmation) would normally be invisible to the user. The SubagentHitlProjector solves this by mirroring worker events onto the leader's session src/agentscope/app/_service/_projectors.py
RequireUserConfirmEvent src/agentscope/app/_service/_chat.py61ChatService.run method for the worker invokes all registered EventProjector instances src/agentscope/app/_service/_chat.py102SubagentHitlProjector identifies the event, resolves the leader's session_id, and uses SessionProjection to write a durable "card" to the leader's session src/agentscope/app/_types.py41-56MessageBus, and the Web UI renders a SubagentHitlCard.Title: Worker HITL Projection Flow
Sources: src/agentscope/app/_service/_chat.py74-161 src/agentscope/app/_types.py41-87 src/agentscope/app/message_bus/_keys.py62-101
The ChatService is the central orchestrator for team runs. It manages the assembly of agents with their specific middlewares (like InboxMiddleware) and tools src/agentscope/app/_service/_chat.py90-154 It also handles session locking via MessageBus.session_run to ensure only one run occurs per session at a time src/agentscope/app/_service/_chat.py82-87
Team triggers are handled by the WakeupDispatcher. When a worker reports back via TeamSay, it delivers a HintBlock to the leader's inbox and enqueues a wake trigger src/agentscope/app/_bus_ops.py163-204 The dispatcher then spawns a ChatService.run for the leader to process the worker's report src/agentscope/app/_manager/_wakeup_dispatcher.py65-131
| Code Symbol | Role | Source |
|---|---|---|
EventProjector | Protocol for cross-session event mirroring. | src/agentscope/app/_types.py41 |
SessionProjection | Shared primitive for writing to target session UI feeds. | src/agentscope/app/_service/_session_projection.py |
WakeupDispatcher | Drains the shared trigger queue to spawn runs. | src/agentscope/app/_manager/_wakeup_dispatcher.py65 |
MessageBusKeys | Defines the projection_namespace and projection_field formats. | src/agentscope/app/message_bus/_keys.py67-82 |
Sources: src/agentscope/app/_service/_chat.py74-161 src/agentscope/app/_manager/_wakeup_dispatcher.py65-131 src/agentscope/app/_bus_ops.py163-204 src/agentscope/app/message_bus/_keys.py62-101
Refresh this wiki