AgentUse - Autonomous Agents That Work Without You

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 uses the parent entry’s maxSteps, then the leaf agent’s own maxSteps, then the 100-step default.

Basic Usage

Define a Sub-Agent

Create researcher.agentuse:

---
model: anthropic:claude-haiku-4-5
---

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-5
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-5
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-5
subagents:
  - path: ./researcher.agentuse
    name: custom_researcher  # Override default name
    maxSteps: 25            # Override the default step budget
  - path: ./writer.agentuse
    maxSteps: 100           # Allow more steps for complex writing
---

Path Resolution

All sub-agent paths are resolved relative to the parent agent file’s directory, ensuring portability across different execution contexts.

See Agent Syntax - Subagents for complete path resolution examples and directory structure recommendations.

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-5
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-5
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-5
subagents:
  - path: ./team-lead.agentuse  # ✅ Works
---

# team-lead.agentuse
---
model: anthropic:claude-sonnet-5
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-5
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-5
mcpServers:
  database:
    command: "node"
    args: ["./database-server.js"]  # Relative to parent.agentuse location
subagents:
  - path: ./child.agentuse
---

# child.agentuse
---
model: anthropic:claude-haiku-4-5
mcpServers:
  # 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

Single Responsibility

Each sub-agent should have one clear purpose. This makes them reusable and easier to maintain.

Clear Interfaces

Define clear expectations for what each sub-agent receives and returns.

Error Handling

Parent agents should handle sub-agent failures gracefully.

Performance

Use lighter models (like Haiku) for simple sub-agents to reduce costs and latency.

Testing

Test sub-agents independently before composing them.

Example: Customer Support System

# support-system.agentuse
---
model: anthropic:claude-sonnet-5
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-haiku-4-5
---

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

Performance Optimization

Model Selection

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

Model Override Inheritance

When you use --model, it overrides the model for both the parent and ALL sub-agents:

agentuse run orchestrator.agentuse --model openai:gpt-5.4-mini

See CLI Commands - Model Override for complete details on model override behavior and sub-agent inheritance.

Step Limits

Control sub-agent execution limits:

---
model: anthropic:claude-sonnet-5
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

Getting Started

Building

Running

Reference

Sub-Agents

What are Sub-Agents?

Basic Usage

Define a Sub-Agent

Use the Sub-Agent

Multiple Sub-Agents

Sub-Agent Configuration

Path Resolution

Remote Sub-Agents

Passing Context

Sub-Agent Tool Schema

Advanced Patterns

Conditional Delegation

Limitations: No Nested Sub-Agents

Parallel Processing

Sub-Agent Communication

Tool and Resource Inheritance

System Context

Best Practices

Example: Customer Support System

Performance Optimization

Model Selection

Model Override Inheritance

Step Limits

Debugging Sub-Agents

Enable Verbose Logging

Trace Execution

Test Sub-Agents Individually

Security Considerations

Best Practices for Security

Next Steps

Remote Agents

Examples

​What are Sub-Agents?

​Basic Usage

​Define a Sub-Agent

​Use the Sub-Agent

​Multiple Sub-Agents

​Sub-Agent Configuration

​Path Resolution

​Remote Sub-Agents

​Passing Context

​Sub-Agent Tool Schema

​Advanced Patterns

​Conditional Delegation

​Limitations: No Nested Sub-Agents

​Parallel Processing

​Sub-Agent Communication

​Tool and Resource Inheritance

​System Context

​Best Practices

​Example: Customer Support System

​Performance Optimization

​Model Selection

​Model Override Inheritance

​Step Limits

​Debugging Sub-Agents

​Enable Verbose Logging

​Trace Execution

​Test Sub-Agents Individually

​Security Considerations

​Best Practices for Security

​Next Steps

Remote Agents

Examples

What are Sub-Agents?

Basic Usage

Define a Sub-Agent

Use the Sub-Agent

Multiple Sub-Agents

Sub-Agent Configuration

Path Resolution

Remote Sub-Agents

Passing Context

Sub-Agent Tool Schema

Advanced Patterns

Conditional Delegation

Limitations: No Nested Sub-Agents

Parallel Processing

Sub-Agent Communication

Tool and Resource Inheritance

System Context

Best Practices

Example: Customer Support System

Performance Optimization

Model Selection

Model Override Inheritance

Step Limits

Debugging Sub-Agents

Enable Verbose Logging

Trace Execution

Test Sub-Agents Individually

Security Considerations

Best Practices for Security

Next Steps