Skip to main content

​
What are Sub-Agents?

Sub-agents allow you to create modular, reusable agents that can be composed together. A parent agent can delegate specific tasks to specialized sub-agents through tool calls.
Sub-agents are automatically converted to tools that parent agents can call. Each sub-agent runs with a default limit of 50 steps.

​
Basic Usage

​
Define a Sub-Agent

Create researcher.agentuse: 
---
model: anthropic:claude-3-5-haiku-latest
---

You are a research specialist. Find accurate, relevant information.

## Task
Research the requested topic and provide comprehensive findings.
The agent name is automatically derived from the filename (e.g., researcher.agentuse becomes researcher).

​
Use the Sub-Agent

Create main.agentuse: 
---
model: anthropic:claude-sonnet-4-0
subagents:
  - path: ./researcher.agentuse
---

You coordinate research tasks using specialized agents.

## Task
When asked for information, use the researcher tool to gather data.
Sub-agents are called as tools using their filename (without .agentuse). The researcher.agentuse becomes available as the researcher tool.

​
Multiple Sub-Agents

---
model: anthropic:claude-sonnet-4-0
subagents:
  - path: ./agents/researcher.agentuse
  - path: ./agents/writer.agentuse
  - path: ./agents/editor.agentuse
---

You manage content creation using specialized agents.

## Workflow
1. Use researcher tool to gather information
2. Use writer tool to create initial draft
3. Use editor tool to polish and finalize

​
Sub-Agent Configuration

You can customize sub-agent behavior: 
---
model: anthropic:claude-sonnet-4-0
subagents:
  - path: ./researcher.agentuse
    name: custom_researcher  # Override default name
    maxSteps: 25            # Override default 50 steps
  - path: ./writer.agentuse
    maxSteps: 100           # Allow more steps for complex writing
---

​
Path Resolution

Important: All sub-agent paths are resolved relative to the parent agent file’s directory, not the current working directory. This ensures your agent compositions work consistently regardless of where you run them.

​
How Path Resolution Works

When you define a sub-agent path, it’s always relative to the location of the parent agent file: 
# File: /project/agents/orchestrator.agentuse
---
model: anthropic:claude-sonnet-4-0
subagents:
  - path: ./researcher.agentuse          # → /project/agents/researcher.agentuse
  - path: ../utils/helper.agentuse       # → /project/utils/helper.agentuse
  - path: ./team/specialist.agentuse     # → /project/agents/team/specialist.agentuse
---

​
Directory Structure Example

project/
├── agents/
│   ├── orchestrator.agentuse
│   ├── researcher.agentuse
│   └── team/
│       └── specialist.agentuse
└── utils/
    └── helper.agentuse
You can run the orchestrator from any directory: 
# From project root
agentuse run agents/orchestrator.agentuse

# From agents directory
cd agents && agentuse run orchestrator.agentuse

# From anywhere with absolute path
agentuse run /full/path/to/project/agents/orchestrator.agentuse
In all cases, the sub-agent paths resolve correctly based on the orchestrator’s location.

​
Remote Sub-Agents

Remote sub-agents are not currently supported. Sub-agents must be local files accessible via the filesystem.

​
Passing Context

Sub-agents accept optional parameters when called as tools: 
---
model: anthropic:claude-sonnet-4-0
subagents:
  - path: ./data-processor.agentuse
---

You analyze data using specialized processors.

## Task
When given data:
1. Call data_processor tool with task parameter and context
2. Interpret the results
3. Provide insights

Example: data_processor(task="Analyze sales data", context={"period": "Q4 2023"})

​
Sub-Agent Tool Schema

Each sub-agent tool accepts:
  • task (optional string): Additional instructions for the sub-agent
  • context (optional object): Structured data to pass to the sub-agent
The sub-agent receives its original instructions plus any additional task and context.

​
Advanced Patterns

​
Conditional Delegation

---
model: anthropic:claude-sonnet-4-0
subagents:
  - path: ./technical-expert.agentuse
  - path: ./creative-writer.agentuse
  - path: ./data-analyst.agentuse
---

You route requests to appropriate specialists.

## Routing Logic
- Technical questions → call technical_expert tool
- Creative tasks → call creative_writer tool
- Data requests → call data_analyst tool

​
Limitations: No Nested Sub-Agents

Important: Sub-agents cannot have their own sub-agents. Any subagents configuration in a sub-agent file will be ignored.
This limitation is intentional to:
  • Prevent infinite recursion (Agent A → Agent B → Agent A)
  • Avoid deep nesting complexity that’s hard to debug
  • Reduce resource consumption and token usage
  • Keep execution traces manageable
# orchestrator.agentuse
---
model: anthropic:claude-sonnet-4-0
subagents:
  - path: ./team-lead.agentuse  # ✅ Works
---

# team-lead.agentuse
---
model: anthropic:claude-sonnet-4-0
subagents:
  - path: ./developer.agentuse  # ❌ Will be ignored
  - path: ./tester.agentuse      # ❌ Will be ignored
---
Sub-agents only have access to their configured MCP tools, not other sub-agents. Each sub-agent creates its own isolated MCP connections.

​
Parallel Processing

---
model: anthropic:claude-sonnet-4-0
subagents:
  - path: ./analyzer-1.agentuse
  - path: ./analyzer-2.agentuse
  - path: ./analyzer-3.agentuse
---

You process data in parallel using multiple analyzers.

## Task
Split the data and send parts to different analyzer tools.
Combine their results for comprehensive analysis.

You can call multiple tools in sequence or use them to analyze different aspects of the same data.
Sub-agents run sequentially, not in true parallel. The parent agent calls each sub-agent tool one at a time.

​
Sub-Agent Communication

​
Tool and Resource Inheritance

Sub-agents create their own isolated tool environments: 
# parent.agentuse
---
model: anthropic:claude-sonnet-4-0
mcp_servers:
  database:
    command: "node"
    args: ["./database-server.js"]  # Relative to parent.agentuse location
subagents:
  - path: ./child.agentuse
---

# child.agentuse
---
model: anthropic:claude-3-5-haiku-latest
mcp_servers:
  # Child defines its own MCP servers
  filesystem:
    command: "npx"
    args: ["@modelcontextprotocol/server-filesystem"]
  custom:
    command: "../tools/my-server"  # Relative to child.agentuse location
---
MCP server commands with relative paths are resolved from the agent file’s directory, ensuring consistent behavior across different execution contexts.
Each sub-agent manages its own MCP connections and tools. They don’t automatically inherit parent tools.

​
System Context

All sub-agents receive consistent system context:
  • Date and time information
  • Autonomous agent behavior prompts
  • Model-specific system messages (e.g., “Claude Code” for Anthropic models)

​
Best Practices

Each sub-agent should have one clear purpose. This makes them reusable and easier to maintain.
Define clear expectations for what each sub-agent receives and returns.
Parent agents should handle sub-agent failures gracefully.
Use lighter models (like Haiku) for simple sub-agents to reduce costs and latency.
Test sub-agents independently before composing them.

​
Example: Customer Support System

# support-system.agentuse
---
model: anthropic:claude-sonnet-4-0
subagents:
  - path: ./agents/ticket-classifier.agentuse
  - path: ./agents/knowledge-base.agentuse
  - path: ./agents/escalation-handler.agentuse
---

You manage customer support requests.

## Workflow
1. Call ticket_classifier tool to categorize the issue
2. Call knowledge_base tool to find solutions
3. If unresolved, call escalation_handler tool

Each tool returns structured output you can use to make decisions.

# ticket-classifier.agentuse
---
model: anthropic:claude-3-5-haiku-latest
---

Classify support tickets into categories:
- Technical issue
- Billing question
- Feature request
- General inquiry

​
Performance Optimization

​
Model Selection

# Optimize model usage
---
model: anthropic:claude-sonnet-4-0  # Smart coordinator
subagents:
  - path: ./simple-task.agentuse  # Can use claude-3-5-haiku-latest
  - path: ./complex-task.agentuse  # Can use anthropic:claude-opus-4-1
---

​
Model Override Inheritance

When you use the --model CLI flag, it overrides the model for both the parent agent and ALL sub-agents. This allows you to test entire agent hierarchies with different models without editing any files.
# Override all agents to use GPT-5-mini (parent + all sub-agents)
agentuse run orchestrator.agentuse --model openai:gpt-5-mini

# All agents will use claude-3-5-haiku regardless of their configured models
agentuse run complex-system.agentuse -m anthropic:claude-3-5-haiku-latest
This is particularly useful for:
  • Cost optimization: Use cheaper models for development/testing
  • A/B testing: Compare entire workflows with different models
  • Environment-specific deployments: Different models for dev/staging/prod
  • Quick experiments: Try new models without modifying agent files

​
Step Limits

Control sub-agent execution limits: 
---
model: anthropic:claude-sonnet-4-0
subagents:
  - path: ./quick-task.agentuse
    maxSteps: 10              # Limit for simple tasks
  - path: ./complex-task.agentuse  
    maxSteps: 200             # More steps for complex work
---
Default step limit for sub-agents is 50 (compared to 1000 for main agents).

​
Debugging Sub-Agents

​
Enable Verbose Logging

agentuse run main.agentuse --verbose

​
Trace Execution

DEBUG=agent:* agentuse run main.agentuse

​
Test Sub-Agents Individually

# Test sub-agent directly
agentuse run ./agents/researcher.agentuse "test query"

​
Security Considerations

Sub-agents run with the same system permissions as the parent process. Each sub-agent:
  • Creates its own MCP connections with full permissions
  • Can access any tools defined in its configuration
  • Runs with the same file system and network access
  • Has access to environment variables

​
Best Practices for Security

  • Audit sub-agent configurations carefully
  • Use minimal necessary permissions in MCP server configs
  • Avoid loading sub-agents from untrusted sources
  • Review sub-agent instructions for potentially harmful commands
  • Use disallowedTools in MCP configs to restrict dangerous tools

​
Next Steps

Remote Agents

Learn about remote agent execution

Examples

See sub-agent examples
⌘I