logo
Development
OverviewDevSpaceWorkSpaceAPI ReferenceBest PracticeChangelog
Search
English
WorkSpace / App Settings / Subagent Management
Subagent Registration and Management
Last updated：9 days ago

Subagent Registration and Management

Overview

The subagent management page is used to pre-register subagents with specific configurations. Pre-registered subagents are automatically injected into the main Agent's system prompt, and the Agent automatically selects and invokes them when it encounters a matching task.

Subagent Management Page-CN

Pre-registered Subagent Configuration

Basic Configuration

Parameter Description Required
name Subagent name Yes
description Capability description (injected into the parent Agent's system prompt) Yes
systemPrompt Identity/role definition Yes

Tool Configuration

Parameter Description
tools Tool allowlist (if omitted, inherits all of the parent's tools)
disallowedTools Tool blocklist (excluded on top of what is inherited)
skills List of available skill IDs
mcpServers List of available MCP server names

Execution Configuration

Parameter Description Default
model Overrides the parent's LLM model Inherits from parent
maxTurns Maximum number of loop turns 50
canSpawn Whether it can create sub-level subagents false
maxSpawnDepth Maximum nesting depth (1-3) 1

Management Operations

Operation Description
Add Create a new pre-registered subagent
Edit Modify the configuration of an existing subagent
Delete Remove a pre-registered subagent
Sort Adjust the order of subagents in the list

Interaction with Work Conversations

Pre-registered subagents interact with Work conversations in the following ways:

  1. System prompt injection: The subagent's name and description are listed in the main Agent's system prompt
  2. Automatic matching: The LLM automatically selects the appropriate subagent based on the semantics of the user's message
  3. Manual invocation: The user can specify a particular subagent to use during the conversation

Use Case Examples

Subagent Name Description Specialized Tools
Code Reviewer Responsible for code review and quality analysis Read File, Search Files, Glob
Document Writer Responsible for writing and formatting documents Write File, Edit, Web Fetch
Research Assistant Responsible for information search and material collection Web Fetch, Search Files
Data Analyst Responsible for data processing and analysis Bash, Read File, Write File

How-to Guide: Creating a Pre-registered Subagent

Steps

  1. Open APP → Settings → Subagents
  2. Click Add Subagent
  3. Fill in the basic information:
    • Name: e.g., "Code Reviewer"
    • Description: e.g., "Responsible for reviewing code quality, finding potential bugs, and providing optimization suggestions" (this description is injected into the main Agent's system prompt to help the Agent determine when to invoke it)
    • System Prompt: e.g., "You are a senior code review expert who focuses on code quality, performance, security, and maintainability..."
  4. (Optional) Configure the tool allowlist/blocklist
  5. (Optional) Override the model or adjust maxTurns
  6. Save

Configuration Example: "Code Reviewer" Subagent

名称: 代码审查员 描述: 负责审查代码质量、发现潜在 bug、提供优化建议。擅长多语言代码分析。 系统提示: 你是一位资深代码审查专家。你的职责是： 1. 分析代码质量和可维护性 2. 发现潜在的 bug 和安全漏洞 3. 提供具体的优化建议 请对每个问题给出严重等级（低/中/高）和修复建议。 工具白名单: Read File, Search Files, Glob Files（只需要读取能力，不需要修改） 模型: Claude Sonnet 4（推理能力强） maxTurns: 30 canSpawn: false（不需要再委派）
                      
                      名称: 代码审查员
描述: 负责审查代码质量、发现潜在 bug、提供优化建议。擅长多语言代码分析。
系统提示: 你是一位资深代码审查专家。你的职责是：
  1. 分析代码质量和可维护性
  2. 发现潜在的 bug 和安全漏洞
  3. 提供具体的优化建议
  请对每个问题给出严重等级（低/中/高）和修复建议。
工具白名单: Read File, Search Files, Glob Files（只需要读取能力，不需要修改）
模型: Claude Sonnet 4（推理能力强）
maxTurns: 30
canSpawn: false（不需要再委派）
This code block in the floating window

The Practical Impact of maxSpawnDepth

Setting Meaning Applicable Scenario Cost Impact
1 (default) The subagent cannot create sub-level subagents Simple specialized tasks Low
2 The subagent can create one more layer of subagents Moderately complex tasks that require secondary decomposition Medium
3 Maximum nesting depth, allowing three levels of delegation Highly complex multi-step tasks High (each level of subagent consumes tokens independently)

Note: Each level of subagent starts an independent Agent Loop (50 turns by default) and consumes independent LLM tokens. A depth of 3 means that up to 4 Agents may run simultaneously (main + 3 levels of subagents), and the cost may be several times that of a single Agent.

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 subagent. For occasional temporary task decomposition, simply let the Agent create one automatically.