Subagents

Agent Runtimes supports multi-agent delegation via the in-repo subagents capability (agent_runtimes/subagents/). An orchestrator agent can delegate tasks to specialised subagents, each running independently with its own model and instructions.

How It Works

1. Agent spec declares a subagents block listing the available subagents
2. Code generation (make specs) compiles the YAML into Python/TypeScript catalogs
3. Agent creation reads the spec and builds a SubagentsCapability via factory.py
4. Runtime — the orchestrator agent receives a delegate_task tool and a dynamic system prompt listing the subagents

Architecture

┌─────────────────────────────────────────────────────┐
│                 Orchestrator Agent                   │
│  (receives task, check_task, list_active_tasks, …)  │
│                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │  Researcher  │  │   Writer    │  │  General    │ │
│  │  subagent    │  │  subagent   │  │  Purpose    │ │
│  └─────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────┘

Agent Spec Configuration

Add a subagents block to any agent YAML spec:

subagents:
  default_model: "bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0"
  include_general_purpose: true
  max_nesting_depth: 0
  subagents:
    - name: researcher
      description: "Researches topics and provides analysis"
      instructions: >
        You are a thorough research assistant...
      preferred_mode: sync
      typical_complexity: moderate
      can_ask_questions: true
      max_questions: 3

    - name: writer
      description: "Writes clear, structured content"
      instructions: >
        You are a skilled technical writer...
      preferred_mode: sync
      typical_complexity: moderate
      can_ask_questions: false

See the agentspecs subagents documentation for the full YAML schema reference.

Runtime Integration

Capability Factory

When an agent is created from a spec containing subagents, the capability factory in agent_runtimes/capabilities/factory.py automatically:

1. Converts each SubAgentspecConfig into a SubagentDefinition
2. Creates a SubagentsCapability with the resolved default model
3. Adds it to the agent's capability list

from agent_runtimes.subagents import SubagentDefinition, SubagentsCapability

capability = SubagentsCapability(
    subagents=[
        SubagentDefinition(
            name="researcher",
            description="Researches topics...",
            instructions="You are a thorough research assistant...",
        ),
    ],
    default_model="bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    include_general_purpose=True,
)

Delegation Tool

The orchestrator agent receives a single delegation tool at runtime:

Tool	Description
delegate_task	Run a named subagent on a self-contained task and return its final answer

Each delegation runs the subagent in an isolated child run. Token and request usage are forwarded to the parent run so budget limits stay accurate.

Dynamic System Prompt

The SubagentsCapability contributes a system prompt section listing the available subagents with their names and descriptions, so the model knows what it can delegate to.

TypeScript Types

The TypeScript types for subagents are available in the @datalayer/agent-runtimes package:

import type { SubAgentspecConfig, SubAgentsConfig } from '@datalayer/agent-runtimes';

const config: SubAgentsConfig = {
  subagents: [
    {
      name: 'researcher',
      description: 'Researches topics...',
      instructions: 'You are a thorough research assistant...',
      preferredMode: 'sync',
      typicalComplexity: 'moderate',
      canAskQuestions: true,
      maxQuestions: 3,
    },
  ],
  defaultModel: 'bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0',
  includeGeneralPurpose: true,
  maxNestingDepth: 0,
};

Example

The AgentSubagentsExample demonstrates the full workflow:

EXAMPLE=AgentSubagentsExample npm run dev

This creates an orchestrator agent from the example-subagents spec with a researcher and writer subagent. The sidebar shows available subagents and delegation tools.

Suggestions to Try

• "Research the pros and cons of Python async patterns and write a summary."
• "Find recent advances in LLM fine-tuning and create a brief report."
• "Investigate best practices for REST API design and draft a style guide."

Demo Spec

The built-in example-subagents spec is available in agentspecs/agentspecs/agents/example-subagents.yaml and demonstrates:

• Two subagents (researcher and writer) with distinct roles
• A general-purpose subagent included as fallback