logo
Development
OverviewDevSpaceWorkSpaceAPI ReferenceBest PracticeChangelog
Search
English
WorkSpace / App Settings / Subagent Management
Subagent Registration and Management
Last updated：in about 7 hours

Subagent Registration and Management

Overview

The SubAgent page (Settings → GWork Settings → SubAgent) is used to pre-register sub-agents with specific configurations. Pre-registered sub-agents are automatically injected into the main Agent's system prompt, and the main Agent dispatches tasks to them (via dispatch_sub_agent) when it encounters a matching task.

SubAgent page

Until you create one, the page shows "No sub-agents registered yet" — the dispatch_sub_agent tool is only enabled for the main Agent once at least one sub-agent exists.

Sub-agent Configuration

Click + SubAgent to open the Create sub-agent form:

Field Description Required
ID Unique identifier, e.g. code-reviewer Yes
Name Display name, e.g. Code Reviewer Yes
Description What the sub-agent does. The main Agent reads this to decide when to dispatch to it — keep it accurate and concise Yes
System prompt Loaded when dispatched; becomes the sub-agent's identity and directly affects task quality Yes
Max turns Maximum loop turns per dispatch. Leave empty to use the app default (50) No
Can spawn sub-agents Whether this sub-agent may create further sub-agents No (on by default)

Click Save to register it. Sub-agents inherit the main Agent's model and tools unless the task context says otherwise.

Management Operations

Operation Description
+ SubAgent Create a new pre-registered sub-agent
Edit Open an existing sub-agent and modify its configuration
Delete Remove a pre-registered sub-agent

Interaction with Conversations

  1. System prompt injection: each sub-agent's Name and Description are listed in the main Agent's system prompt
  2. Automatic matching: the main Agent selects the appropriate sub-agent based on the semantics of the task
  3. Manual invocation: you can name a sub-agent in your message to ask for it explicitly

Sub-agent runs are bounded by Max turns here and by the Sub-agent timeout (minutes) in Settings → Task Control (default 30 minutes; completed work is preserved when a sub-agent is cancelled).

Use Case Examples

Sub-agent Description Typical tools
Code Reviewer Reviews code for correctness, performance and security Read file, Search in files, Find files
Document Writer Writes and formats documents Write file, docx / pptx skills
Research Assistant Searches and collects information Browser, web-search skill
Data Analyst Processes and analyzes data Run command, Read file, Write file

How-to Guide: Creating a Pre-registered Sub-agent

  1. Open App → ⚙ Settings → SubAgent
  2. Click + SubAgent
  3. Fill in:
    • ID: code-reviewer
    • Name: Code Reviewer
    • Description: "Reviews code for correctness, performance, and security. Good at multi-language code analysis."
    • System prompt: "You are a senior code reviewer. Analyze code for correctness, performance, security and maintainability. For each issue give a severity (low / medium / high) and a fix suggestion."
  4. (Optional) set Max turns (e.g. 30) and turn off Can spawn sub-agents if further delegation is not needed
  5. Click Save

The Practical Impact of Spawning Depth

Setting Meaning Cost Impact
Can spawn sub-agents: off The sub-agent cannot create sub-level sub-agents Low
Can spawn sub-agents: on The sub-agent may delegate further Higher — each level runs its own Agent Loop and consumes its own tokens / credits

Note: Each level of sub-agent starts an independent Agent Loop (50 turns by default). Deep delegation can multiply the cost of a single task; keep spawning off for simple specialized roles.

Pre-registration vs. Auto-creation: How to Choose?

Comparison Pre-registration (dispatch_sub_agent) Auto-creation (create_local_sub_agent)
Configuration Configured in advance, once and for all Created temporarily by the Agent on demand each time
Consistency Uses the same configuration each time, with stable results The Agent may assign different identities and tools each time
Suitable Scenarios Professional roles used frequently and repeatedly One-off temporary task decomposition
System Prompt Automatically injected into the main Agent, so the Agent knows it can be used The Agent decides on its own whether to create one

Recommendation: If you frequently need a certain type of task (such as code review, document writing, or data analysis), create a pre-registered sub-agent. For occasional temporary task decomposition, simply let the Agent create one automatically.