Subagents System

The subagents system enables task delegation to specialized agents, allowing Qwen Code to handle complex, multi-step tasks autonomously through parallel execution and specialized expertise.

Overview

Subagents are lightweight, single-use AI agents that:

Execute tasks autonomously with their own tool access
Run in parallel for improved performance
Have specialized system prompts and configurations
Communicate through events for real-time UI updates
Are stateless and terminate after completing their task

Architecture

Core Components

SubagentManager
│
├── Subagent Configuration (Markdown + YAML)
│   ├── name: string
│   ├── description: string
│   ├── tools: string[]
│   ├── systemPrompt: string
│   └── modelConfig: {...}
│
├── SubAgentScope (Runtime)
│   ├── GeminiChat
│   ├── ToolRegistry (subset)
│   ├── ContextState
│   └── Event Emitter
│
└── TaskTool (Interface)
    └── Delegates to subagents

Configuration Storage

Subagents are configured as Markdown files with YAML frontmatter: File Format:

---
name: code-reviewer
description: Reviews code for quality, security, and best practices
tools:
  - read_file
  - grep_search
  - glob
modelConfig:
  model: qwen-coder-plus
  temperature: 0.3
runConfig:
  max_turns: 10
  max_time_minutes: 5
color: blue
---

# Code Review Agent

You are a code review specialist. Your task is to:

1. Analyze code for quality and maintainability
2. Identify security vulnerabilities
3. Check for best practices compliance
4. Suggest improvements

Be thorough but concise in your feedback.

Storage Hierarchy

Subagents are stored at different levels with priority:

Session Level (highest priority)
- Provided at runtime
- Read-only
- Use: Temporary, specialized agents for specific sessions
Project Level
- Location: .qwen/agents/ in project directory
- Use: Project-specific agents
User Level
- Location: ~/.qwen/agents/ in home directory
- Use: Personal agents across all projects
Extension Level
- Provided by installed extensions
- Read-only
Built-in Level (lowest priority)
- Embedded in codebase
- Always available

Creating Subagents

Using the SubagentManager

import { SubagentManager } from '@qwen-code/qwen-code-core';

const manager = new SubagentManager(config);

const subagentConfig = {
  name: 'test-runner',
  description: 'Runs tests and analyzes results',
  tools: ['run_shell_command', 'read_file', 'grep_search'],
  systemPrompt: `
    You are a test execution specialist.
    
    Your responsibilities:
    1. Run the test suite
    2. Analyze failures
    3. Provide clear summaries
    4. Suggest fixes when possible
  `,
  modelConfig: {
    model: 'qwen-coder-plus',
    temperature: 0.2,
  },
  runConfig: {
    max_turns: 15,
    max_time_minutes: 10,
  },
};

await manager.createSubagent(subagentConfig, {
  level: 'project',  // or 'user'
  overwrite: false,
});

Via Command Line

Users can create subagents using the /agents command:

# In Qwen Code CLI
/agents create test-runner

This opens an interactive wizard to configure the subagent.

Manual File Creation

Create a Markdown file in the appropriate directory:

# Project-level agent
.qwen/agents/my-agent.md

# User-level agent
~/.qwen/agents/my-agent.md

Configuration Options

Required Fields

name: string           # Unique identifier
description: string    # When and how to use this agent
tools: string[]       # Array of tool names
systemPrompt: string  # Agent's instructions

Optional Fields

modelConfig:
  model: string              # Model name (default: uses main config)
  temperature: number        # 0.0-2.0 (default: 1.0)
  topP: number              # 0.0-1.0 (default: 0.95)

runConfig:
  max_turns: number         # Max conversation turns (default: 20)
  max_time_minutes: number  # Max execution time (default: 30)
  terminate_mode: string    # 'graceful' or 'immediate'

color: string               # Display color in UI

Tool Configuration

Available Tools:

File system: read_file, write_file, edit, glob, grep_search, list_directory
Shell: run_shell_command
Memory: save_memory
Task: task (for nested delegation)
Web: web_fetch, web_search
LSP: lsp_* tools
MCP: Dynamically loaded MCP tools

Example Tool Configuration:

tools:
  - read_file
  - edit
  - run_shell_command
  - grep_search

If tools is omitted, the subagent inherits all available tools.

Runtime Execution

Executing a Subagent

Subagents are invoked through the task tool:

// Model uses task tool
task({
  description: 'Code review',
  prompt: 'Review the authentication module for security issues',
  subagent_type: 'code-reviewer',
});

Execution Flow

Initialization:
- Load subagent configuration
- Create SubAgentScope instance
- Initialize tool registry with allowed tools
- Set up event emitter
Context Setup:
- Apply system prompt with variable substitution
- Set initial chat history
- Configure model parameters
Execution Loop:
- Send prompt to model
- Process tool calls
- Handle confirmations (if needed)
- Execute tools
- Send results back to model
- Repeat until completion or limits
Termination:
- Model returns final text response
- Emit finish event
- Clean up resources
- Return result to parent agent

Event-Driven Updates

Subagents emit events for real-time UI updates:

// Event types
export enum SubAgentEventType {
  START = 'start',
  ROUND = 'round',
  TOOL_CALL = 'tool_call',
  TOOL_RESULT = 'tool_result',
  APPROVAL_REQUEST = 'approval_request',
  FINISH = 'finish',
  ERROR = 'error',
  USAGE = 'usage',
}

// Example event listener
const emitter = new SubAgentEventEmitter();

emitter.on(SubAgentEventType.START, (event: SubAgentStartEvent) => {
  console.log(`Subagent ${event.name} started`);
});

emitter.on(SubAgentEventType.TOOL_CALL, (event: SubAgentToolCallEvent) => {
  console.log(`Calling tool: ${event.tool.name}`);
});

emitter.on(SubAgentEventType.FINISH, (event: SubAgentFinishEvent) => {
  console.log(`Subagent finished: ${event.result}`);
});

Context State and Templating

Subagents support variable substitution in system prompts:

// Define context
const context = new ContextState();
context.set('project_name', 'my-app');
context.set('language', 'TypeScript');

// System prompt with variables
const systemPrompt = `
You are working on the ${project_name} project.
This is a ${language} codebase.

Your task: ...
`;

// Variables are replaced at runtime:
// "You are working on the my-app project."
// "This is a TypeScript codebase."

Parallel Execution

Multiple subagents can run simultaneously:

// Launch multiple tasks in parallel
await Promise.all([
  task({
    description: 'Code review',
    prompt: 'Review the auth module',
    subagent_type: 'code-reviewer',
  }),
  task({
    description: 'Run tests',
    prompt: 'Execute the test suite',
    subagent_type: 'test-runner',
  }),
  task({
    description: 'Update docs',
    prompt: 'Generate API documentation',
    subagent_type: 'documentation-writer',
  }),
]);

The Task tool supports parallel execution when multiple tool calls are made in a single model response.

Statistics and Telemetry

Subagents track execution statistics:

export interface SubagentStatsSummary {
  totalDurationMs: number;
  rounds: number;
  totalToolCalls: number;
  successfulToolCalls: number;
  failedToolCalls: number;
  inputTokens?: number;
  outputTokens?: number;
  totalTokens?: number;
  estimatedCost?: number;
}

Statistics are logged for analytics (respecting privacy settings):

logSubagentExecution(
  config,
  new SubagentExecutionEvent(
    subagentName,
    stats.totalDurationMs,
    stats.rounds,
    stats.totalToolCalls,
    outcome,
  ),
);

Best Practices

Design Guidelines

Single Responsibility: Each subagent should have a clear, focused purpose
Minimal Tools: Only grant access to necessary tools
Clear Instructions: Write detailed, unambiguous system prompts
Appropriate Limits: Set reasonable time and turn limits
Error Handling: Account for failures in parent agent logic

System Prompt Tips

# Good System Prompt Structure

## Role
You are a [specific role] specialist.

## Responsibilities
1. [Specific task 1]
2. [Specific task 2]
3. [Specific task 3]

## Guidelines
- [Important guideline 1]
- [Important guideline 2]

## Output Format
Provide your response in this format:
[Expected format description]

Tool Selection

Read-only Tools (always safe):

read_file
grep_search
glob
list_directory

Modifying Tools (require careful consideration):

write_file
edit
run_shell_command

Delegation Tools (for complex tasks):

task (enable nested delegation)

Built-in Subagents

Qwen Code includes built-in subagents:

General Purpose Agent

name: general-purpose
description: Handles complex multi-step tasks with full tool access
tools: [all tools]

Code Search Agent

name: code-search
description: Specialized in finding code and patterns across the codebase
tools:
  - read_file
  - grep_search
  - glob
  - list_directory

See packages/core/src/subagents/builtin-agents.ts for all built-in agents.

Validation

Subagent configurations are validated on:

Creation
Loading
Execution

Validation Rules:

Name must be valid (alphanumeric, hyphens, underscores)
Description must not be empty
System prompt must not be empty
Tools must exist in the tool registry
Model config must be valid
Run config must have reasonable limits

Error Handling

export enum SubagentErrorCode {
  NOT_FOUND = 'NOT_FOUND',
  ALREADY_EXISTS = 'ALREADY_EXISTS',
  INVALID_CONFIG = 'INVALID_CONFIG',
  FILE_ERROR = 'FILE_ERROR',
  EXECUTION_ERROR = 'EXECUTION_ERROR',
  TIMEOUT = 'TIMEOUT',
  MAX_TURNS_EXCEEDED = 'MAX_TURNS_EXCEEDED',
}

export class SubagentError extends Error {
  constructor(
    message: string,
    public code: SubagentErrorCode,
    public subagentName?: string,
  ) {
    super(message);
    this.name = 'SubagentError';
  }
}

Testing Subagents

Test subagent configurations before deployment:

import { describe, it, expect } from 'vitest';
import { SubagentManager } from '@qwen-code/qwen-code-core';

describe('MySubagent', () => {
  it('should validate configuration', async () => {
    const config = {
      name: 'my-agent',
      description: 'Test agent',
      tools: ['read_file'],
      systemPrompt: 'Test prompt',
    };

    const manager = new SubagentManager(mockConfig);
    await expect(
      manager.createSubagent(config, { level: 'user' }),
    ).resolves.not.toThrow();
  });

  it('should execute successfully', async () => {
    // Test execution logic
  });
});

Next Steps

Configuration System - Understanding configuration
Task Tool Reference - Using the task delegation tool
Testing Guide - Testing subagents

Contributing

Core Concepts

Tools Reference

Subagents System

Subagents System

Overview

Architecture

Core Components

Configuration Storage

Storage Hierarchy

Creating Subagents

Using the SubagentManager

Via Command Line

Manual File Creation

Configuration Options

Required Fields

Optional Fields

Tool Configuration

Runtime Execution

Executing a Subagent

Execution Flow

Event-Driven Updates

Context State and Templating

Parallel Execution

Statistics and Telemetry

Best Practices

Design Guidelines

System Prompt Tips

Tool Selection

Built-in Subagents

General Purpose Agent

Code Search Agent

Validation

Error Handling

Testing Subagents

Next Steps

Contributing

Core Concepts

Tools Reference

​Subagents System

​Overview

​Architecture

​Core Components

​Configuration Storage

​Storage Hierarchy

​Creating Subagents

​Using the SubagentManager

​Via Command Line

​Manual File Creation

​Configuration Options

​Required Fields

​Optional Fields

​Tool Configuration

​Runtime Execution

​Executing a Subagent

​Execution Flow

​Event-Driven Updates

​Context State and Templating

​Parallel Execution

​Statistics and Telemetry

​Best Practices

​Design Guidelines

​System Prompt Tips

​Tool Selection

​Built-in Subagents

​General Purpose Agent

​Code Search Agent

​Validation

​Error Handling

​Testing Subagents

​Next Steps

Subagents System

Overview

Architecture

Core Components

Configuration Storage

Storage Hierarchy

Creating Subagents

Using the SubagentManager

Via Command Line

Manual File Creation

Configuration Options

Required Fields

Optional Fields

Tool Configuration

Runtime Execution

Executing a Subagent

Execution Flow

Event-Driven Updates

Context State and Templating

Parallel Execution

Statistics and Telemetry

Best Practices

Design Guidelines

System Prompt Tips

Tool Selection

Built-in Subagents

General Purpose Agent

Code Search Agent

Validation

Error Handling

Testing Subagents

Next Steps