Subagents are independent instances that execute tasks while keeping your main conversation clean and focused. Think of them as temporary assistants that handle specific jobs, bringing process isolation and context preservation by offloading work to separate instances.
goose can autonomously decide to use subagents when it determines they would be beneficial for your task - you don't always need to explicitly request them. This happens automatically in autonomous [permission mode](/docs/guides/managing-tools/goose-permissions) (the default). Subagents are disabled in manual approval, smart approval, and chat-only modes.
To use subagents, ask goose to delegate tasks using natural language. goose automatically decides when to spawn subagents and handles their lifecycle. You can:
| **Sequential** (Default) | Tasks execute one after another | "first...then", "after" | `"First analyze the code, then generate documentation"` |
| **Parallel** | Tasks execute simultaneously | "parallel", "simultaneously", "at the same time", "concurrently" | `"Create three HTML templates in parallel"` |
When goose delegates work to a subagent, you can see the subagent's tool calls in real-time. This transparency helps you understand what the subagent is doing and verify it's on the right track.
If a subagent fails or times out (5-minute default), you will receive no output from that subagent. For parallel execution, if any subagent fails, you get results only from the successful ones.
Internal subagents spawn goose instances to handle tasks using your current session's context and extensions. There are two ways to configure and execute internal subagents:
"Use 2 subagents to create hello.html with 'Hello World' content and goodbye.html with 'Goodbye World' content in parallel"
```
**Tool Output:**
```json
{
"execution_summary": {
"total_tasks": 2,
"successful_tasks": 2,
"failed_tasks": 0,
"execution_time_seconds": 16.2
},
"task_results": [
{
"task_id": "create_hello_html",
"status": "success",
"result": "Successfully created hello.html with Hello World content"
},
{
"task_id": "create_goodbye_html",
"status": "success",
"result": "Successfully created goodbye.html with Goodbye World content"
}
]
}
```
### Recipes
Use [recipe](/docs/guides/recipes/) files to define specific instructions, extensions, and behavior for subagents. Recipes provide reusable configurations that can be shared and referenced by name.
**Creating a Recipe File**
`code-reviewer.yaml`
```yaml
id: code-reviewer
version: 1.0.0
title: "Code Review Assistant"
description: "Specialized subagent for code quality and security analysis"
instructions: |
You are a code review assistant. Analyze code and provide feedback on:
- Code quality and readability
- Security vulnerabilities
- Performance issues
- Best practices adherence
activities:
- Analyze code structure
- Check for security issues
- Review performance patterns
extensions:
- type: builtin
name: developer
display_name: Developer
timeout: 300
bundled: true
parameters:
- key: focus_area
input_type: string
requirement: optional
description: "Specific area to focus on (security, performance, readability, etc.)"
default: "general"
prompt: |
Please review the following code focusing on {{focus_area}} aspects.
Provide specific, actionable feedback with examples.
External subagents let you bring in AI agents from other providers and platforms, enabling goose to coordinate and integrate your workflow with the broader ecosystem. In the below example, we use Codex as a subagent by running it as an MCP server:
| **Max Turns** | 25 | Use natural language, set `GOOSE_SUBAGENT_MAX_TURNS`, or configure `settings.max_turns` in [recipes](/docs/guides/recipes/recipe-reference#settings) or subagent tool calls |
"Use subagents to analyze code, limit each to 5 turns"
```
```
"Use a research subagent with 30 turns and 20-minute timeout to investigate quantum computing trends"
```
**Environment variable:** Set `GOOSE_SUBAGENT_MAX_TURNS` to change the default max turns for all subagents.
### Extension Control
Control which tools and capabilities subagents can access. By default, subagents inherit all extensions from your main session, but you can restrict access for security, focus or performance.
The `delegate` and `load` tools are provided by the `summon` platform extension, which is enabled by default. If you are using a [recipe](/docs/guides/recipes/) with an explicit `extensions` block, you must include `summon` in that list or the `delegate` tool will not be available:
```yaml
extensions:
- type: platform
name: summon
# ... your other extensions
```
Recipes that define [`sub_recipes`](/docs/guides/recipes/subrecipes) have `summon` auto-injected.
description: 'Deep dive into goose subagents. Walk through building an app using 6 specialized AI agents for advanced workflow automation and development.',
title: 'Flight School - Choosing the Right Tools for AI Work',
description: 'Discover the differences between subagents and subrecipes for efficient task execution in goose. Learn which approach is best for your workflow.',
title: 'Flight School - Choosing the Right Tools for AI Work',
description: 'Discover the differences between subagents and subrecipes for efficient task execution in goose. Learn which approach is best for your workflow.',
title: 'How to Choose Between Subagents and Subrecipes in goose',
description: 'Detailed guide to subagents and subrecipes in goose. Compare reusability, setup complexity, and get practical advice for choosing the right approach.',
