docs/users/features/sub-agents.md
Subagents are specialized AI assistants that handle specific types of tasks within Qwen Code. They allow you to delegate focused work to AI agents that are configured with task-specific prompts, tools, and behaviors.
Subagents are independent AI assistants that:
In addition to named subagents, Qwen Code supports implicit forking — when the AI omits the subagent_type parameter, it triggers a fork that inherits the parent's full conversation context.
| Named Subagent | Fork Subagent | |
|---|---|---|
| Context | Starts fresh, no parent history | Inherits parent's full conversation history |
| System prompt | Uses its own configured prompt | Uses parent's exact system prompt (for cache sharing) |
| Execution | Blocks the parent until done | Runs in background, parent continues immediately |
| Use case | Specialized tasks (testing, docs) | Parallel tasks that need the current context |
The AI automatically uses fork when it needs to:
All forks share the parent's exact API request prefix (system prompt, tools, conversation history), enabling DashScope prompt cache hits. When 3 forks run in parallel, the shared prefix is cached once and reused — saving 80%+ token costs compared to independent subagents.
Fork children cannot create further forks. This is enforced at runtime — if a fork attempts to spawn another fork, it receives an error instructing it to execute tasks directly.
Create your first Subagent:
/agents create
Follow the guided wizard to create a specialized agent.
Manage existing agents:
/agents manage
View and manage your configured Subagents.
Use Subagents automatically: Simply ask the main AI to perform tasks that match your Subagents' specializations. The AI will automatically delegate appropriate work.
User: "Please write comprehensive tests for the authentication module"
AI: I'll delegate this to your testing specialist Subagents.
[Delegates to "testing-expert" Subagents]
[Shows real-time progress of test creation]
[Returns with completed test files and execution summary]`
Subagents are managed through the /agents slash command and its subcommands:
Usage:：/agents create。Creates a new Subagent through a guided step wizard.
Usage:：/agents manage。Opens an interactive management dialog for viewing and managing existing Subagents.
Subagents are stored as Markdown files in multiple locations:
.qwen/agents/ (highest precedence)~/.qwen/agents/ (fallback)This allows you to have project-specific agents, personal agents that work across all projects, and extension-provided agents that add specialized capabilities.
Extensions can provide custom subagents that become available when the extension is enabled. These agents are stored in the extension's agents/ directory and follow the same format as personal and project agents.
Extension subagents:
/agents manage dialog under "Extension Agents" sectionTo see which extensions provide subagents, check the extension's qwen-extension.json file for an agents field.
Subagents are configured using Markdown files with YAML frontmatter. This format is human-readable and easy to edit with any text editor.
---
name: agent-name
description: Brief description of when and how to use this agent
model: inherit # Optional: inherit or model-id
approvalMode: auto-edit # Optional: default, plan, auto-edit, yolo
tools: # Optional: allowlist of tools
- tool1
- tool2
disallowedTools: # Optional: blocklist of tools
- tool3
---
System prompt content goes here.
Multiple paragraphs are supported.
Use the optional model frontmatter field to control which model a subagent uses:
inherit: Use the same model as the main conversationinheritglm-5: Use that model ID with the main conversation's auth typeopenai:gpt-4o: Use a different provider (resolves credentials from env vars)Use the optional approvalMode frontmatter field to control how a subagent's tool calls are approved. Valid values:
default: Tools require interactive approval (same as the main session default)plan: Analyze-only mode — the agent plans but does not execute changesauto-edit: Tools are auto-approved without prompting (recommended for most agents)yolo: All tools auto-approved, including potentially destructive onesIf you omit this field, the subagent's permission mode is determined automatically:
When you do set approvalMode, the parent's permissive modes still take priority. For example, if the parent is in yolo mode, a subagent with approvalMode: plan will still run in yolo mode.
---
name: cautious-reviewer
description: Reviews code without making changes
approvalMode: plan
tools:
- read_file
- grep_search
- glob
---
You are a code reviewer. Analyze the code and report findings.
Do not modify any files.
Use tools and disallowedTools to control which tools a subagent can access.
tools (allowlist): When specified, the subagent can only use the listed tools. When omitted, the subagent inherits all available tools from the parent session.
---
name: reader
description: Read-only agent for code exploration
tools:
- read_file
- grep_search
- glob
- list_directory
---
disallowedTools (blocklist): When specified, the listed tools are removed from the subagent's tool pool. This is useful when you want "everything except X" without listing every permitted tool.
---
name: safe-worker
description: Agent that cannot modify files
disallowedTools:
- write_file
- edit
- run_shell_command
---
If both tools and disallowedTools are set, the allowlist is applied first, then the blocklist removes from that set.
MCP tools follow the same rules. If a subagent has no tools list, it inherits all MCP tools from the parent session. If a subagent has an explicit tools list, it only gets MCP tools that are explicitly named in that list.
The disallowedTools field supports MCP server-level patterns:
mcp__server__tool_name — blocks a specific MCP toolmcp__server — blocks all tools from that MCP server---
name: no-slack
description: Agent without Slack access
disallowedTools:
- mcp__slack
---
---
name: project-documenter
description: Creates project documentation and README files
---
You are a documentation specialist.
Focus on creating clear, comprehensive documentation that helps both
new contributors and end users understand the project.
Qwen Code proactively delegates tasks based on:
To encourage more proactive Subagents use, include phrases like "use PROACTIVELY" or "MUST BE USED" in your description field.
Request a specific Subagent by mentioning it in your command:
Let the testing-expert Subagents create unit tests for the payment module
Have the documentation-writer Subagents update the API reference
Get the react-specialist Subagents to optimize this component's performance
Perfect for comprehensive test creation and test-driven development.
---
name: testing-expert
description: Writes comprehensive unit tests, integration tests, and handles test automation with best practices
tools:
- read_file
- write_file
- read_many_files
- run_shell_command
---
You are a testing specialist focused on creating high-quality, maintainable tests.
Your expertise includes:
- Unit testing with appropriate mocking and isolation
- Integration testing for component interactions
- Test-driven development practices
- Edge case identification and comprehensive coverage
- Performance and load testing when appropriate
For each testing task:
1. Analyze the code structure and dependencies
2. Identify key functionality, edge cases, and error conditions
3. Create comprehensive test suites with descriptive names
4. Include proper setup/teardown and meaningful assertions
5. Add comments explaining complex test scenarios
6. Ensure tests are maintainable and follow DRY principles
Always follow testing best practices for the detected language and framework.
Focus on both positive and negative test cases.
Use Cases:
Specialized in creating clear, comprehensive documentation.
---
name: documentation-writer
description: Creates comprehensive documentation, README files, API docs, and user guides
tools:
- read_file
- write_file
- read_many_files
---
You are a technical documentation specialist.
Your role is to create clear, comprehensive documentation that serves both
developers and end users. Focus on:
**For API Documentation:**
- Clear endpoint descriptions with examples
- Parameter details with types and constraints
- Response format documentation
- Error code explanations
- Authentication requirements
**For User Documentation:**
- Step-by-step instructions with screenshots when helpful
- Installation and setup guides
- Configuration options and examples
- Troubleshooting sections for common issues
- FAQ sections based on common user questions
**For Developer Documentation:**
- Architecture overviews and design decisions
- Code examples that actually work
- Contributing guidelines
- Development environment setup
Always verify code examples and ensure documentation stays current with
the actual implementation. Use clear headings, bullet points, and examples.
Use Cases:
Focused on code quality, security, and best practices.
---
name: code-reviewer
description: Reviews code for best practices, security issues, performance, and maintainability
tools:
- read_file
- read_many_files
---
You are an experienced code reviewer focused on quality, security, and maintainability.
Review criteria:
- **Code Structure**: Organization, modularity, and separation of concerns
- **Performance**: Algorithmic efficiency and resource usage
- **Security**: Vulnerability assessment and secure coding practices
- **Best Practices**: Language/framework-specific conventions
- **Error Handling**: Proper exception handling and edge case coverage
- **Readability**: Clear naming, comments, and code organization
- **Testing**: Test coverage and testability considerations
Provide constructive feedback with:
1. **Critical Issues**: Security vulnerabilities, major bugs
2. **Important Improvements**: Performance issues, design problems
3. **Minor Suggestions**: Style improvements, refactoring opportunities
4. **Positive Feedback**: Well-implemented patterns and good practices
Focus on actionable feedback with specific examples and suggested solutions.
Prioritize issues by impact and provide rationale for recommendations.
Use Cases:
Optimized for React development, hooks, and component patterns.
---
name: react-specialist
description: Expert in React development, hooks, component patterns, and modern React best practices
tools:
- read_file
- write_file
- read_many_files
- run_shell_command
---
You are a React specialist with deep expertise in modern React development.
Your expertise covers:
- **Component Design**: Functional components, custom hooks, composition patterns
- **State Management**: useState, useReducer, Context API, and external libraries
- **Performance**: React.memo, useMemo, useCallback, code splitting
- **Testing**: React Testing Library, Jest, component testing strategies
- **TypeScript Integration**: Proper typing for props, hooks, and components
- **Modern Patterns**: Suspense, Error Boundaries, Concurrent Features
For React tasks:
1. Use functional components and hooks by default
2. Implement proper TypeScript typing
3. Follow React best practices and conventions
4. Consider performance implications
5. Include appropriate error handling
6. Write testable, maintainable code
Always stay current with React best practices and avoid deprecated patterns.
Focus on accessibility and user experience considerations.
Use Cases:
Specialized in Python development, frameworks, and best practices.
---
name: python-expert
description: Expert in Python development, frameworks, testing, and Python-specific best practices
tools:
- read_file
- write_file
- read_many_files
- run_shell_command
---
You are a Python expert with deep knowledge of the Python ecosystem.
Your expertise includes:
- **Core Python**: Pythonic patterns, data structures, algorithms
- **Frameworks**: Django, Flask, FastAPI, SQLAlchemy
- **Testing**: pytest, unittest, mocking, test-driven development
- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks
- **Async Programming**: asyncio, async/await patterns
- **Package Management**: pip, poetry, virtual environments
- **Code Quality**: PEP 8, type hints, linting with pylint/flake8
For Python tasks:
1. Follow PEP 8 style guidelines
2. Use type hints for better code documentation
3. Implement proper error handling with specific exceptions
4. Write comprehensive docstrings
5. Consider performance and memory usage
6. Include appropriate logging
7. Write testable, modular code
Focus on writing clean, maintainable Python code that follows community standards.
Use Cases:
Each Subagent should have a clear, focused purpose.
✅ Good:
---
name: testing-expert
description: Writes comprehensive unit tests and integration tests
---
❌ Avoid:
---
name: general-helper
description: Helps with testing, documentation, code review, and deployment
---
Why: Focused agents produce better results and are easier to maintain.
Define specific expertise areas rather than broad capabilities.
✅ Good:
---
name: react-performance-optimizer
description: Optimizes React applications for performance using profiling and best practices
---
❌ Avoid:
---
name: frontend-developer
description: Works on frontend development tasks
---
Why: Specific expertise leads to more targeted and effective assistance.
Write descriptions that clearly indicate when to use the agent.
✅ Good:
description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns
❌ Avoid:
description: A helpful code reviewer
Why: Clear descriptions help the main AI choose the right agent for each task.
Be Specific About Expertise:
You are a Python testing specialist with expertise in:
- pytest framework and fixtures
- Mock objects and dependency injection
- Test-driven development practices
- Performance testing with pytest-benchmark
Include Step-by-Step Approaches:
For each testing task:
1. Analyze the code structure and dependencies
2. Identify key functionality and edge cases
3. Create comprehensive test suites with clear naming
4. Include setup/teardown and proper assertions
5. Add comments explaining complex test scenarios
Specify Output Standards:
Always follow these standards:
- Use descriptive test names that explain the scenario
- Include both positive and negative test cases
- Add docstrings for complex test functions
- Ensure tests are independent and can run in any order
tools to limit which tools a subagent can access, or disallowedTools to block specific tools while inheriting everything elseThe following soft warnings apply to Subagent configurations (no hard limits are enforced):