# Sub-Agents
URL: /docs/framework/sub-agents
Source: /app/src/content/docs/framework/sub-agents.mdx

import { DocImage } from '@/components/DocImage';

<DocImage title="Sub-Agents" />

**Intelligent task delegation with specialized agents working in coordination**

import { Step, Steps } from 'fumadocs-ui/components/steps';

## Overview

Sub-Agents enable sophisticated multi-agent coordination where a main agent intelligently delegates tasks to specialized sub-agents. Each sub-agent has its own expertise, capabilities, and role, working together to complete complex workflows that would be challenging for a single agent.

**New**: Sub-Agents now integrate seamlessly with Graph workflows, enabling hierarchical task distribution across complex workflow orchestration systems.

## Creating Sub-Agents

Sub-agents are created independently and then attached to a main coordinator agent:

```typescript
import { Agent } from '@astreus-ai/astreus';

// Create specialized sub-agents
const researcher = await Agent.create({
  name: 'ResearcherBot',
  model: 'gpt-4o',
  systemPrompt: 'You are an expert researcher who gathers and analyzes information thoroughly.',
  memory: true,
  knowledge: true
});

const writer = await Agent.create({
  name: 'WriterBot',
  model: 'gpt-4o',
  systemPrompt: 'You are a skilled content writer who creates engaging, well-structured content.',
  vision: true
});

const analyst = await Agent.create({
  name: 'AnalystBot', 
  model: 'gpt-4o',
  systemPrompt: 'You are a data analyst who provides insights and recommendations.',
  useTools: true
});

// Create main agent with sub-agents
const mainAgent = await Agent.create({
  name: 'CoordinatorAgent',
  model: 'gpt-4o',
  systemPrompt: 'You coordinate complex tasks between specialized sub-agents.',
  subAgents: [researcher, writer, analyst]
});
```

## Delegation Strategies

### Auto Delegation

The main agent uses LLM intelligence to analyze tasks and assign them optimally:

```typescript
const result = await mainAgent.ask(
  'Research AI market trends, analyze the data, and write an executive summary',
  {
    useSubAgents: true,
    delegation: 'auto'  // AI-powered task distribution
  }
);
```

<Steps>
  <Step>
    ### Task Analysis

    Main agent analyzes the complex task using LLM reasoning.
  </Step>

  <Step>
    ### Agent Matching

    Evaluates each sub-agent's capabilities and specializations.
  </Step>

  <Step>
    ### Optimal Assignment

    Creates specific subtasks for the most appropriate agents.
  </Step>

  <Step>
    ### Coordinated Execution

    Manages execution flow and result aggregation.
  </Step>
</Steps>

### Manual Delegation

Explicitly assign specific tasks to specific agents using their IDs:

```typescript
const result = await mainAgent.ask(
  'Complex multi-step project',
  {
    useSubAgents: true,
    delegation: 'manual',
    taskAssignment: {
      [researcher.id]: 'Research market opportunities in healthcare AI',
      [analyst.id]: 'Analyze market size and growth potential',
      [writer.id]: 'Create executive summary with recommendations'
    }
  }
);
```

### Sequential Delegation

Sub-agents work in sequence, building on previous results:

```typescript
const result = await mainAgent.ask(
  'Create a comprehensive business plan for an AI startup',
  {
    useSubAgents: true,
    delegation: 'sequential'  // Each agent builds on the previous work
  }
);
```

## Coordination Patterns

```mermaid
graph TD
    A[Main Coordinator Agent] --> B{Task Analysis}
    B -->|Research Tasks| C[ResearcherBot]
    B -->|Analysis Tasks| D[AnalystBot]
    B -->|Content Tasks| E[WriterBot]
    
    C --> F[Research Results]
    D --> G[Analysis Results]
    E --> H[Written Content]
    
    F --> I[Result Aggregation]
    G --> I
    H --> I
    
    I --> J[Final Output]
    
    style A fill:#f9f,stroke:#333,stroke-width:4px
    style C fill:#bbf,stroke:#333,stroke-width:2px
    style D fill:#bfb,stroke:#333,stroke-width:2px
    style E fill:#fbb,stroke:#333,stroke-width:2px
```

### Parallel Execution

Sub-agents work simultaneously for maximum efficiency:

```typescript
const result = await mainAgent.ask(
  'Multi-faceted analysis task',
  {
    useSubAgents: true,
    delegation: 'auto',
    coordination: 'parallel'  // All agents work concurrently
  }
);
```

### Sequential Execution

Sub-agents work in order with context passing:

```typescript
const result = await mainAgent.ask(
  'Research → Analyze → Report workflow',
  {
    useSubAgents: true,
    delegation: 'auto', 
    coordination: 'sequential'  // Agents work in dependency order
  }
);
```

## Sub-Agent Configuration

### Specialized Roles

Configure sub-agents for specific expertise areas:

```typescript
// Research Specialist
const researcher = await Agent.create({
  name: 'ResearchSpecialist',
  systemPrompt: 'You conduct thorough research using multiple sources and methodologies.',
  knowledge: true,  // Access to knowledge base
  memory: true,     // Remember research context
  useTools: true    // Use research tools
});

// Content Creator
const creator = await Agent.create({
  name: 'ContentCreator', 
  systemPrompt: 'You create compelling content across different formats and audiences.',
  vision: true,     // Process visual content
  useTools: true    // Use content creation tools
});

// Technical Analyst
const analyst = await Agent.create({
  name: 'TechnicalAnalyst',
  systemPrompt: 'You analyze technical data and provide actionable insights.',
  useTools: true    // Use analysis tools
});
```

## Graph Integration

Sub-Agents work seamlessly with Graph workflows for complex orchestration:

```typescript
import { Agent, Graph } from '@astreus-ai/astreus';

// Create specialized sub-agents
const researcher = await Agent.create({
  name: 'ResearchBot',
  systemPrompt: 'You conduct thorough research and analysis.',
  knowledge: true
});

const writer = await Agent.create({
  name: 'WriterBot',
  systemPrompt: 'You create compelling content and reports.',
  vision: true
});

// Main coordinator with sub-agents
const coordinator = await Agent.create({
  name: 'ProjectCoordinator',
  systemPrompt: 'You coordinate complex projects using specialized teams.',
  subAgents: [researcher, writer]
});

// Create sub-agent aware graph
const projectGraph = new Graph({
  name: 'Market Analysis Project',
  defaultAgentId: coordinator.id,
  subAgentAware: true,
  optimizeSubAgentUsage: true
}, coordinator);

// Add tasks with intelligent sub-agent delegation
const researchTask = projectGraph.addTaskNode({
  name: 'Market Research',
  prompt: 'Research AI healthcare market trends and opportunities',
  useSubAgents: true,
  subAgentDelegation: 'auto'
});

const reportTask = projectGraph.addTaskNode({
  name: 'Executive Report',
  prompt: 'Create comprehensive executive report based on research',
  dependencies: [researchTask],
  useSubAgents: true,
  subAgentCoordination: 'sequential'
});

// Execute with performance monitoring
const result = await projectGraph.run();
console.log('Performance:', projectGraph.generateSubAgentPerformanceReport());
```

### Graph Sub-Agent Features

* **Automatic Detection**: Graph nodes automatically use sub-agents when beneficial
* **Context Passing**: Workflow context flows to sub-agents for better coordination
* **Performance Optimization**: Real-time monitoring and automatic strategy adjustment
* **Flexible Configuration**: Per-node sub-agent settings with inheritance from graph config

## Advanced Examples

### Content Production Pipeline

```typescript
const contentPipeline = await Agent.create({
  name: 'ContentPipeline',
  model: 'gpt-4o',
  subAgents: [researcher, writer, analyst]
});

const blogPost = await contentPipeline.ask(
  'Create a comprehensive blog post about quantum computing applications in finance',
  {
    useSubAgents: true,
    delegation: 'auto',
    coordination: 'sequential'
  }
);
```

### Market Research Workflow

```typescript
const marketResearch = await Agent.create({
  name: 'MarketResearchTeam',
  model: 'gpt-4o',
  subAgents: [researcher, analyst, writer]
});

const report = await marketResearch.ask(
  'Analyze the fintech market and create investor presentation',
  {
    useSubAgents: true,
    delegation: 'manual',
    coordination: 'parallel',
    taskAssignment: {
      [researcher.id]: 'Research fintech market trends and competitors',
      [analyst.id]: 'Analyze market data and financial projections',
      [writer.id]: 'Create compelling investor presentation'
    }
  }
);
```