aaif-goose--goose/documentation/docs/guides/context-engineering/subagents.mdx

---
title: Subagents
sidebar_position: 2
sidebar_label: Subagents
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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.

<details>
  <summary>Subagents Walkthrough</summary>
  <iframe
    class="aspect-ratio"
    src="https://youtube.com/embed/Uk4TtJUykK4"
    title="Subagents Explained"
    frameBorder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowFullScreen
  ></iframe>
</details>

## How to Use Subagents

:::tip Autonomous Subagent Creation
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:

1. **Request specialized help**: "Use a code reviewer to analyze this function for security issues"
2. **Reference specific recipes**: "Use the 'security-auditor' recipe to scan this endpoint"  
3. **Run parallel tasks**: "Create three HTML templates simultaneously"
4. **Delegate complex work**: "Research quantum computing developments and summarize findings"
5. **Control extension access**: "Create a subagent with only the developer extension to refactor the code"

You can run multiple subagents sequentially or in parallel.

| Type | Description | Trigger Keywords | Example |
|------|-------------|------------------|---------|
| **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"` |

## Monitoring Subagent Activity

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.

<Tabs groupId="interface">
  <TabItem value="desktop" label="goose Desktop" default>
    Subagent tool calls appear as expandable sections within the conversation. Click to expand and see the full details of each tool call, including:
    - The tool name being invoked
    - Arguments passed to the tool
    - Tool output and results
  </TabItem>
  <TabItem value="cli" label="goose CLI">
    Subagent tool calls are displayed inline with visual indicators showing the tool name and extension. For example:

    ```text
    [subagent:16] text_editor | developer
    ```

    Each tool call shows:
    - The subagent identifier (e.g., `subagent:16`)
    - The tool name (e.g., `text_editor`)
    - The extension providing the tool (e.g., `developer`)
  </TabItem>
</Tabs>

:::info
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

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:

1. **Direct Prompts** - Quick, one-off tasks using natural language instructions
2. **Recipes** - Reusable, structured configurations for specialized subagent behavior

### Direct Prompts
Direct prompts provided for one-off tasks using natural language prompts. The main agent automatically configures the subagent based on your request.

**goose Prompt:**
```
"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.
```

**Place your recipe file where goose can find it**
- Set [`GOOSE_RECIPE_PATH`](/docs/guides/recipes/recipe-reference#recipe-location) environment variable to your recipe directory
- Or place it in your current working directory

**goose Prompt**
```
Use the "code-reviewer" recipe to analyze the authentication feature I implemented
```

**goose Output**
```
I'll use your code-reviewer recipe to create a specialized subagent for this analysis.

🤖 Subagent created using code-reviewer recipe
💭 Analyzing authentication function for security issues...
🔧 Scanning code structure and patterns...
⚠️  Security vulnerabilities detected!

## Code Review Results

### Critical Issues Found:
1. **SQL Injection Vulnerability**: Direct string interpolation in SQL query
2. **Missing Password Hashing**: Plain text password comparison

### Recommendations:
- Use parameterized queries or ORM
- Implement proper password hashing (bcrypt, scrypt)
- Add input validation and sanitization
```

## External Subagents

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:

**[goose Configuration File](/docs/guides/config-files)** (`.~/.config/goose/config.yaml `):
```yaml
subagent:
  args:
  - mcp-server
  bundled: true
  cmd: codex
  description: OpenAI Codex CLI Subagent
  enabled: true
  env_keys:
  - OPENAI_API_KEY
  envs: {}
  name: subagent
  timeout: 300
  type: stdio
```

**External Tool Configuration** (`~/.codex/config.toml`):
```toml
# Use fast model for quick responses
# model = "codex-mini-latest"
disable_response_storage = true

# Never prompt for approval - auto-execute
approval_policy = "never"

[sandbox]
mode = "workspace-write"
```

**goose Prompt:**
```
"Use the codex subagent to analyze my codebase structure and identify the main components"
```

**goose Output:**

```md
Based on my analysis of your codebase, here are the main components:

1. **Core Agent System** (`crates/goose/src/agents/`)
   - Agent orchestration and session management
   - Tool execution framework
   - Extension system integration

2. **CLI Interface** (`crates/goose-cli/`)
   - Command-line interface and session handling
   - Configuration management

3. **ACP Server** (`crates/goose/src/acp/`)
   - Agent Client Protocol endpoints
   - HTTP/WebSocket communication for real-time interaction

4. **Desktop UI** (`ui/desktop/`)
   - Electron-based desktop application
   - TypeScript frontend with React components

The architecture follows a modular design with clear separation between the core agent logic, interfaces, and UI components.
```

## Suggested Use Cases

**Independent Operations**
- Creating multiple files with similar structure
- Basic data processing tasks
- File transformations and generations

**Context Preservation**
- Complex analysis that generates lots of tool output
- Specialized tasks better handled by dedicated agents
- Keeping main conversation focused on high-level decisions

**Process Isolation**
- Tasks that might fail without affecting main workflow
- Operations requiring different configurations
- Experimental or exploratory work

## Lifecycle and Cleanup

Subagents are temporary instances that exist only for task execution. After the task is completed, no manual intervention is needed for cleanup.

## Configuration

Subagents use the following pre-configured settings, but you can override any defaults using natural language in your prompts.

### Default Settings
| Parameter | Default | How to Customize |
|-----------|---------|------------------|
| **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 |
| **Timeout** | 5 minutes | Request longer timeout in your prompt |
| **Extensions** | Inherited from parent | Specify which extensions to use in your prompt |
| **Return Mode** | All subagent information provided in main session | Specify how much detail you want in your prompt |

:::tip Advanced Customization
You can also customize subagent behavior by editing the `subagent_system.md` [prompt template](/docs/guides/context-engineering/prompt-templates).
:::

### Customizing Settings in Prompts

You can override any default by including the setting in your natural language request:

**Examples:**
```
"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.

:::note Summon Extension
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.
:::

**Examples:**
```
"Create a subagent to write a summary, but don't give it file access"
```

```
"Use a subagent with only code editing tools to refactor main.py"
```

### Return Mode Control
Choose how much information goose provides from its subagents in your main session.

**Full Details (Default):** See all tool executions and reasoning steps
```
"Create a subagent to debug this issue - I want to see the full investigation process"
```

**Summary Only:** Get just the final result to keep your conversation clean
```
"Use a subagent to research this topic and summarize the key findings"
```

## Security Constraints

Subagents operate with restricted tool access to ensure safe execution and prevent interference with the main session.

### Allowed Operations

Subagents have access to these safe operations:

- **Extension discovery**: Search for available extensions to understand what tools are available
- **Resource access**: Read and list resources from enabled extensions for context
- **Extension tools**: Use tools from extensions specified in recipes or inherited from the parent session

### Restricted Operations

The following operations are blocked to ensure subagents remain focused on their assigned tasks without affecting the broader system state:

- **Subagent spawning**: Cannot create additional subagents to prevent infinite recursion
- **Extension management**: Cannot enable, disable, or modify extensions to avoid conflicts with the main session
- **Schedule management**: Cannot create, modify, or delete scheduled tasks to prevent interference with parent workflows

:::info
Subagents can browse extensions for suggestions but cannot enable them to avoid modifying the parent session.
:::

## Additional Resources

import ContentCardCarousel from '@site/src/components/ContentCardCarousel';
import subagentsVsSubrecipes from '@site/blog/2025-09-26-subagents-vs-subrecipes/subrecipes-vs-subagents.png';
import agentCoordination from '@site/blog/2025-08-14-agent-coordination-patterns/agent-coordination.png';

<ContentCardCarousel
  items={[
      {
      type: 'blog',
      title: 'Agents, Subagents, and Multi Agents: What They Are and When to Use Them',
      description: 'Compare agents, subagents, and multi agents in AI workflows. Learn how they work together and practical scenarios for each approach.',
      thumbnailUrl: agentCoordination,
      linkUrl: '/blog/2025/08/14/agent-coordination-patterns',
      date: '2025-08-14',
      duration: '4 min read'
    },
    {
      type: 'video',
      title: 'How I Built an App with 6 Subagents',
      description: 'Deep dive into goose subagents. Walk through building an app using 6 specialized AI agents for advanced workflow automation and development.',
      thumbnailUrl: 'https://img.youtube.com/vi/yIBrD5AxtTc/maxresdefault.jpg',
      linkUrl: 'https://www.youtube.com/watch?v=yIBrD5AxtTc',
      date: '2025-10-01',
      duration: '6:53'
    },
    {
      type: 'tutorial',
      title: 'Tutorial: Using Subagents',
      description: 'Spin up a team of subagents to build a fully functional app',
      thumbnailUrl: 'https://goose-docs.ai/assets/images/tutorial-using-subagents-ef265627024db73e73d80e5799ed0c1a.png',
      linkUrl: '/docs/tutorials/subagents',
      date: '2026-01-27',
      duration: '1 hour'
    },
    {
      type: 'video',
      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.',
      thumbnailUrl: 'https://img.youtube.com/vi/joePzlkARjs/maxresdefault.jpg',
      linkUrl: 'https://www.youtube.com/watch?v=joePzlkARjs',
      date: '2025-09-29',
      duration: '6:13'
    },
    {
      type: 'video',
      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.',
      thumbnailUrl: 'https://img.youtube.com/vi/joePzlkARjs/maxresdefault.jpg',
      linkUrl: 'https://www.youtube.com/watch?v=joePzlkARjs',
      date: '2025-09-29',
      duration: '6:13'
    },
    {
      type: 'blog',
      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.',
      thumbnailUrl: subagentsVsSubrecipes,
      linkUrl: '/blog/2025/09/26/subagents-vs-subrecipes',
      date: '2025-09-26',
      duration: '6 min read'
    }
  ]}
/>