> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Subagent Generation

> Spawn specialized agents for complex, independent tasks

## Usage

DeepAgent can spawn subagents to handle complex, multi-step independent tasks with isolated context. The `task` tool is automatically available.

## Tool Signature

```python theme={null}
task(description: str, subagent_type: str = "general-purpose") -> str
```

## Available Subagent Types

1. **general-purpose**: Automatically available, created with same model as parent
2. **Custom agents**: Agents provided in the `subagents` parameter

## When to Use Subagents

* Complex independent tasks that can be fully delegated
* Parallel processing of multiple related tasks
* Specialized expertise requiring focused knowledge
* Context isolation for heavy token usage

## Basic Example

```python theme={null}
import asyncio
from upsonic.agent.deepagent import DeepAgent
from upsonic import Task

async def main():
    agent = DeepAgent(model="anthropic/claude-sonnet-4-5")
    
    task = Task(description="""
    Research Python web frameworks and return a summary.
    
    Then create /reports/frameworks.txt with the summary.
    """)
    
    result = await agent.do_async(task)
    print(result)

asyncio.run(main())
```

## Custom Subagents Example

```python theme={null}
import asyncio
from upsonic.agent.deepagent import DeepAgent
from upsonic import Agent, Task

async def main():
    # Create specialized subagents
    researcher = Agent(
        model="openai/gpt-4o-mini",
        name="researcher",
        role="Research Specialist",
        system_prompt="You are a research expert focused on gathering information"
    )
    
    writer = Agent(
        model="openai/gpt-4o-mini",
        name="writer",
        role="Technical Writer",
        system_prompt="You are a technical writing expert"
    )
    
    # Create DeepAgent with subagents
    agent = DeepAgent(
        model="anthropic/claude-sonnet-4-5",
        subagents=[researcher, writer]
    )
    
    task = Task(description="""
    Research AI trends and write a technical report based on research
    
    Save the final report to /reports/ai_trends.txt
    """)
    
    result = await agent.do_async(task)
    print(result)

asyncio.run(main())
```

## Parallel Subagents Example

```python theme={null}
import asyncio
from upsonic.agent.deepagent import DeepAgent
from upsonic import Agent, Task

async def main():
    # Create multiple specialized subagents
    python_expert = Agent(
        model="openai/gpt-4o-mini",
        name="python-expert",
        system_prompt="Python programming expert"
    )
    
    js_expert = Agent(
        model="openai/gpt-4o-mini",
        name="js-expert",
        system_prompt="JavaScript programming expert"
    )
    
    agent = DeepAgent(
        model="anthropic/claude-sonnet-4-5",
        subagents=[python_expert, js_expert]
    )
    
    task = Task(description="""
    Research Python web frameworks and JavaScript web frameworks in parallel.
    
    Then synthesize findings into /reports/comparison.txt
    """)
    
    result = await agent.do_async(task)
    print(result)

asyncio.run(main())
```

## Adding Subagents Dynamically

```python theme={null}
import asyncio
from upsonic.agent.deepagent import DeepAgent
from upsonic import Agent, Task

async def main():
    agent = DeepAgent(model="anthropic/claude-sonnet-4-5")
    
    # Add subagent after creation
    analyst = Agent(
        model="openai/gpt-4o-mini",
        name="analyst",
        role="AI Analyst",
        system_prompt="Data analysis expert"
    )
    agent.add_subagent(analyst)
    
    task = Task(description="""
    Analyze AI trends.
    Save results to /analysis/trends.txt
    """)
    
    result = await agent.do_async(task)
    print(result)

asyncio.run(main())
```

## Key Points

* Subagents execute autonomously and return a single result
* Subagents have isolated context (no memory sharing)
* Each subagent must have a `name` attribute
* Use parallel subagents for independent tasks