Skip to main content
Subagents are specialized agents that concentrate on sub-tasks delegated by a parent agent. Parallel subagents, each focused on a small part, achieve the overall goal faster. They are also more successful because the context that they provide to their language model contains much less noise. Each subagent has its own instructions, model, and tools. Subagents are ideal for:
  • Breaking complex tasks into specialized subtasks.
  • Parallel processing of independent work items.
  • Role-based delegation (researcher, writer, reviewer).
  • Isolating concerns with specialized tools and expertise.

​
Quick Start

Define subagents in your agent configuration:
images/main/main.py
from autonomy import Agent, Model, Node


async def main(node):
  await Agent.start(
    node=node,
    name="manager",
    instructions="""
    You are a project manager who coordinates research and writing tasks.
    
    When given a topic:
    1. Delegate research to the researcher subagent
    2. Delegate writing to the writer subagent
    3. Combine their work into a final response
    """,
    model=Model("claude-sonnet-4-v1"),
    subagents={
      "researcher": {
        "instructions": "You are a researcher who finds accurate information on topics.",
        "model": Model("claude-sonnet-4-v1"),
        "auto_start": True
      },
      "writer": {
        "instructions": "You are a writer who creates clear, engaging content.",
        "model": Model("nova-pro-v1"),
        "auto_start": True
      }
    }
  )


Node.start(main)
images/main/Dockerfile
FROM ghcr.io/build-trust/autonomy-python
COPY . .
ENTRYPOINT ["python", "main.py"]
autonomy.yaml
name: subagent-example
pods:
  - name: main-pod
    public: true
    containers:
      - name: main
        image: main
The parent agent delegates tasks: 
curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"message":"Write a report about quantum computing"}' \
  "https://CLUSTER-ZONE.cluster.autonomy.computer/agents/manager"
The manager agent will:
  1. Delegate research to the researcher subagent
  2. Delegate writing to the writer subagent
  3. Combine their responses

​
Configuring Subagents

Subagents are defined in the subagents parameter: 
await Agent.start(
  node=node,
  name="parent",
  instructions="You coordinate work across specialized subagents",
  model=Model("claude-sonnet-4-v1"),
  subagents={
    "role_name": {
      "instructions": "Subagent instructions",
      "model": Model("model-name"),
      "auto_start": True,  # Optional: start automatically on first use
      "tools": [...],      # Optional: subagent-specific tools
      "max_iterations": 10,  # Optional: override default
      "max_execution_time": 60,  # Optional: timeout in seconds
      "enable_long_term_memory": True,  # Optional: persistent memory
    }
  }
)

​
Configuration Options

Required:
  • instructions - System instructions defining the subagent’s role and behavior
Optional:
  • model - Model to use. Defaults to parent’s model if not specified
  • auto_start - Automatically start subagent on first delegation. Default: False
  • tools - List of tools available to the subagent
  • max_iterations - Maximum reasoning loops. Default: 10
  • max_execution_time - Timeout in seconds. Default: 60
  • max_messages_in_short_term_memory - Message limit. Default: 100
  • max_tokens_in_short_term_memory - Token limit. Default: 8000
  • enable_long_term_memory - Enable persistent memory. Default: False
  • runner_filter - Filter for distributing subagents across nodes

​
Subagent Tools

When you configure subagents, the parent agent automatically gets access to delegation tools:

​
start_subagent

Start a subagent manually: 
# Agent calls: start_subagent(role="researcher")
# Returns: Confirmation that subagent started
Not usually needed - use auto_start: True instead.

​
delegate_to_subagent

Delegate a single task to a subagent: 
# Agent calls: delegate_to_subagent(
#   role="researcher",
#   task="Research the history of quantum computing"
# )
# Returns: The researcher's response
Parameters:
  • role - The subagent role name (must match a key in subagents config)
  • task - Task description or prompt to send to the subagent

​
delegate_to_subagents_parallel

Delegate multiple tasks to parallel subagent instances: 
# Agent calls: delegate_to_subagents_parallel(
#   role="researcher",
#   tasks=[
#     "Research quantum computing history",
#     "Research quantum computing applications",
#     "Research quantum computing challenges"
#   ]
# )
# Returns: Array of results in the same order as tasks
Parameters:
  • role - The subagent role name
  • tasks - List of task descriptions
Creates one subagent instance per task and processes them concurrently.

​
list_subagents

List configured and running subagents: 
# Agent calls: list_subagents()
# Returns: Information about configured and running subagents

​
stop_subagent

Stop a running subagent: 
# Agent calls: stop_subagent(role="researcher")
# Returns: Confirmation that subagent stopped
Rarely needed - subagents are automatically cleaned up when the parent stops.

​
Delegation Patterns

​
Sequential Delegation

Delegate tasks one at a time in sequence: 
await Agent.start(
  node=node,
  name="sequential_manager",
  instructions="""
  When given a topic to analyze:
  1. First, delegate to 'researcher' to gather information
  2. Then, delegate to 'analyst' to analyze the research
  3. Finally, delegate to 'writer' to create a report
  
  Use delegate_to_subagent for each step. Wait for results before proceeding.
  """,
  model=Model("claude-sonnet-4-v1"),
  subagents={
    "researcher": {
      "instructions": "Research topics thoroughly and provide factual information",
      "auto_start": True
    },
    "analyst": {
      "instructions": "Analyze research data and identify key insights",
      "auto_start": True
    },
    "writer": {
      "instructions": "Write clear, engaging reports from analysis",
      "auto_start": True
    }
  }
)

​
Parallel Delegation

Process multiple independent tasks concurrently: 
await Agent.start(
  node=node,
  name="parallel_manager",
  instructions="""
  When given a list of topics to research:
  1. Use delegate_to_subagents_parallel to research all topics at once
  2. Each topic will be processed by a separate researcher instance
  3. Combine the results into a comprehensive summary
  """,
  model=Model("claude-sonnet-4-v1"),
  subagents={
    "researcher": {
      "instructions": "Research a single topic and provide detailed findings",
      "model": Model("claude-sonnet-4-v1"),
      "auto_start": True
    }
  }
)
Example usage: 
curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"message":"Research these topics: quantum computing, AI ethics, blockchain"}' \
  "https://CLUSTER-ZONE.cluster.autonomy.computer/agents/parallel_manager"
The manager creates 3 researcher instances and processes all topics concurrently.

​
Role-Based Delegation

Different subagents for different expertise: 
await Agent.start(
  node=node,
  name="content_manager",
  instructions="""
  You coordinate content creation:
  - Use 'researcher' for fact-finding
  - Use 'writer' for drafting content
  - Use 'editor' for reviewing and improving content
  - Use 'fact_checker' to verify claims
  
  Choose the right subagent based on the task at hand.
  """,
  model=Model("claude-sonnet-4-v1"),
  subagents={
    "researcher": {
      "instructions": "Research topics and gather accurate information",
      "tools": [McpTool("brave_search", "brave_web_search")],
      "auto_start": True
    },
    "writer": {
      "instructions": "Write engaging, clear content",
      "model": Model("claude-sonnet-4-v1"),
      "auto_start": True
    },
    "editor": {
      "instructions": "Review content for clarity, grammar, and style",
      "model": Model("claude-sonnet-4-v1"),
      "auto_start": True
    },
    "fact_checker": {
      "instructions": "Verify factual claims and identify unsupported statements",
      "tools": [McpTool("brave_search", "brave_web_search")],
      "auto_start": True
    }
  }
)

​
Auto-Start Behavior

Subagents start automatically on first use: 
subagents={
  "researcher": {
    "instructions": "You are a researcher",
    "auto_start": True  # Starts automatically when first delegated to
  }
}
With auto_start: True:
  • Parent calls delegate_to_subagent(role="researcher", ...)
  • Framework automatically starts the subagent if not running
  • Task is delegated
  • No need to explicitly call start_subagent()
With auto_start: False (default):
  • Parent must explicitly call start_subagent(role="researcher") first
  • Then can call delegate_to_subagent(role="researcher", ...)
  • Useful when you want explicit control over lifecycle
Recommendation: Use auto_start: True for simpler agent logic.

​
Parallel Processing

Process multiple tasks concurrently with delegate_to_subagents_parallel: 
await Agent.start(
  node=node,
  name="batch_processor",
  instructions="""
  When given a batch of documents to analyze:
  1. Use delegate_to_subagents_parallel with the 'analyzer' role
  2. Pass all documents as separate tasks
  3. Each document will be analyzed by a separate instance
  4. Results come back in the same order as the input
  """,
  model=Model("claude-sonnet-4-v1"),
  subagents={
    "analyzer": {
      "instructions": "Analyze a single document and extract key insights",
      "model": Model("claude-sonnet-4-v1")
    }
  }
)
Example: 
# Parent agent calls:
delegate_to_subagents_parallel(
  role="analyzer",
  tasks=[
    "Analyze document 1: [content...]",
    "Analyze document 2: [content...]",
    "Analyze document 3: [content...]"
  ]
)

# Framework creates 3 analyzer instances, processes all 3 documents concurrently,
# and returns array of results: [result1, result2, result3]
Benefits:
  • Independent tasks complete dramatically faster
  • Scales to dozens of concurrent tasks
  • Automatic cleanup after completion

​
Runner Distribution

For true parallelism across multiple nodes, use runner filters: 
await Agent.start(
  node=node,
  name="distributed_manager",
  instructions="Coordinate work across distributed workers",
  model=Model("claude-sonnet-4-v1"),
  subagent_runner_filter="role=worker",  # Apply to all subagents
  subagents={
    "worker": {
      "instructions": "Process tasks assigned to you",
      "runner_filter": "role=worker,cpu=high"  # Override for this subagent
    }
  }
)
Runner filters:
  • Select which nodes run subagents
  • Distribute work across multiple machines
  • Format: "key1=value1,key2=value2"
  • Subagent-specific runner_filter overrides agent-level subagent_runner_filter
Configure runners in autonomy.yaml: 
name: distributed-app
pods:
  - name: manager-pod
    public: true
    containers:
      - name: manager
        image: manager

  - name: worker-pod
    replicas: 3  # Multiple worker nodes
    labels:
      role: worker
      cpu: high
    containers:
      - name: worker
        image: worker

​
Subagent Memory

Subagents have their own isolated memory: 
subagents={
  "researcher": {
    "instructions": "You are a researcher",
    "enable_long_term_memory": True,  # Enable persistent memory
    "max_messages_in_short_term_memory": 50,  # Limit short-term memory
    "max_tokens_in_short_term_memory": 4000
  }
}
Memory behavior:
  • Each subagent instance maintains its own conversation history
  • Parent agent’s memory is separate from subagent memory
  • Subagents don’t see parent’s conversation history
  • Results return to parent as tool responses
For parallel subagents:
  • Each parallel instance has completely isolated memory
  • Instance A does not see Instance B’s history
  • Each task starts with a clean slate

​
Complete Example

Build a research and writing system with parallel processing:
images/main/main.py
from autonomy import Agent, Model, Node, McpClient, McpTool


async def main(node):
  await Agent.start(
    node=node,
    name="research_coordinator",
    instructions="""
    You coordinate research and writing projects.
    
    When given a topic with multiple aspects:
    1. Break it into specific research questions
    2. Use delegate_to_subagents_parallel to research all questions at once
    3. Synthesize the research findings
    4. Delegate to the writer to create a comprehensive article
    5. Return the final article
    """,
    model=Model("claude-sonnet-4-v1"),
    subagents={
      "researcher": {
        "instructions": """
        You are a thorough researcher who finds accurate, current information.
        Use the brave_web_search tool to find reliable sources.
        Cite your sources in your responses.
        """,
        "model": Model("claude-sonnet-4-v1"),
        "tools": [McpTool("brave_search", "brave_web_search")],
        "auto_start": True,
        "max_execution_time": 120
      },
      "writer": {
        "instructions": """
        You are a skilled writer who creates clear, engaging articles.
        Structure content with clear headings and logical flow.
        Write in an accessible but authoritative tone.
        """,
        "model": Model("claude-sonnet-4-v1"),
        "auto_start": True,
        "max_execution_time": 90
      }
    }
  )


Node.start(
  main,
  mcp_clients=[
    McpClient(name="brave_search", address="http://localhost:8001/sse")
  ]
)
autonomy.yaml
name: research-system
pods:
  - name: main-pod
    public: true
    containers:
      - name: main
        image: main
      
      - name: mcp
        image: ghcr.io/build-trust/mcp-proxy
        env:
          - BRAVE_API_KEY: secrets.BRAVE_API_KEY
        args:
          ["--sse-port", "8001", "--pass-environment", "--",
           "npx", "-y", "@modelcontextprotocol/server-brave-search"]
secrets.yaml
BRAVE_API_KEY: "YOUR_BRAVE_API_KEY"

# Use the system
curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"message":"Write a comprehensive article about renewable energy, covering solar, wind, and hydroelectric power"}' \
  "https://CLUSTER-ZONE.cluster.autonomy.computer/agents/research_coordinator"
What happens:
  1. Coordinator breaks topic into 3 research questions
  2. Creates 3 researcher instances working in parallel
  3. Each researcher uses web search to find current information
  4. Coordinator synthesizes findings
  5. Delegates to writer for final article
  6. Returns polished, well-researched article

​
Best Practices

​
Choose Appropriate Models

Use different models for different subagent roles: 
subagents={
  "quick_classifier": {
    "instructions": "Classify inputs into categories",
    "model": Model("nova-micro-v1")  # Fast, cheap for simple tasks
  },
  "deep_analyzer": {
    "instructions": "Perform deep analysis",
    "model": Model("claude-opus-4-v1")  # Powerful for complex reasoning
  }
}

​
Set Appropriate Timeouts

subagents={
  "web_searcher": {
    "instructions": "Search the web for information",
    "max_execution_time": 120,  # Web searches may take longer
    "tools": [McpTool("brave_search", "brave_web_search")]
  },
  "calculator": {
    "instructions": "Perform calculations",
    "max_execution_time": 30  # Quick operations
  }
}

​
Use auto_start for Simplicity

subagents={
  "helper": {
    "instructions": "Help with tasks",
    "auto_start": True  # Simpler agent logic
  }
}

​
Provide Clear Instructions

Each subagent should have focused, clear instructions: 
subagents={
  "researcher": {
    "instructions": """
    You are a researcher focused solely on gathering information.
    
    Your job:
    - Find accurate, current information on the given topic
    - Use web search when needed
    - Cite sources
    - DO NOT write articles or summaries
    - DO NOT provide opinions, only facts
    """
  }
}

​
Handle Errors Gracefully

Provide error handling guidance in parent agent instructions: 
instructions="""
You coordinate subagents. If a subagent task fails:
1. Check if the error can be resolved (e.g., retry with different parameters)
2. Try an alternative approach if available
3. If all attempts fail, inform the user clearly about what went wrong
"""