Middleware for delegating tasks to specialized SubAgents.

Provides a task tool that allows the main agent to delegate complex, multi-step work to specialized SubAgents. SubAgents run in isolated contexts with their own conversation history, providing token efficiency and clean separation of concerns.

Features

• Dynamic SubAgents: Create SubAgents from configuration at runtime
• Pre-compiled SubAgents: Use pre-built Agent instances
• HITL Propagation: SubAgent interrupts automatically propagate to parent
• Token Efficiency: Parent only sees final result, not SubAgent's internal work
• Process Isolation: SubAgents run as supervised processes

Configuration Options

The middleware accepts these options:

• :subagents - List of SubAgent.Config or SubAgent.Compiled configurations for pre-defined subagents. Defaults to [].

• :model - The chat model for dynamic subagents. Required.

• :middleware - Additional middleware to add to subagents. Defaults to [].

• :block_middleware - List of middleware modules to exclude from general-purpose subagent inheritance. Defaults to []. See "Middleware Filtering" below.

• :include_task_list - Whether to render the ## Available Tasks section (one bullet per configured sub-agent plus general-purpose) into the middleware's system prompt. Defaults to true.

  Set to false when the integrating application supplies the task menu another way. For example, a /commands flow that injects only the relevant task entry on demand to keep the base context lean and reduce the chance of the model picking the wrong task. The task tool's task_name enum still constrains valid values regardless.

Configuration Example

middleware = [
  {SubAgent, [
    model: model,
    subagents: [
      SubAgent.Config.new!(%{
        name: "researcher",
        description: "Research topics using internet search",
        system_prompt: "You are an expert researcher...",
        tools: [internet_search_tool]
      }),
      SubAgent.Compiled.new!(%{
        name: "coder",
        description: "Write code for specific tasks",
        agent: pre_built_coder_agent
      })
    ],
    block_middleware: [ConversationTitle, Summarization]
  ]}
]

Middleware Filtering

When a general-purpose subagent is created, it inherits the parent agent's middleware stack with certain exclusions:

1. SubAgent middleware is ALWAYS excluded - This prevents recursive subagent nesting which could lead to resource exhaustion. You cannot override this.

2. Blocked middleware is excluded - Any modules listed in :block_middleware are filtered out before passing to the subagent.

Example: Blocking Unnecessary Middleware

Some middleware is inappropriate for short-lived subagents:

{SubAgent, [
  model: model,
  subagents: [],

  # These middleware modules won't be inherited by general-purpose subagents
  block_middleware: [
    Sagents.Middleware.ConversationTitle,  # Subagents don't need titles
    Sagents.Middleware.Summarization       # Short tasks don't need summarization
  ]
]}

Pre-configured Subagents

The :block_middleware option only affects general-purpose subagents created dynamically via the task tool. Pre-configured subagents (defined in :subagents) use their own explicitly defined middleware and are NOT affected by this option.

{SubAgent, [
  subagents: [
    # This subagent defines its own middleware - block_middleware doesn't apply
    SubAgent.Config.new!(%{
      name: "researcher",
      middleware: [ConversationTitle]  # Explicitly included
    })
  ],
  block_middleware: [ConversationTitle]  # Only affects general-purpose
]}

Usage Example

# Main agent decides to delegate work
"I need to research renewable energy. I'll use the researcher SubAgent."
→ Calls: task("Research renewable energy impacts", "researcher")

# SubAgent executes independently
# If SubAgent hits HITL interrupt (e.g., internet_search needs approval):
#   1. SubAgent pauses
#   2. Interrupt propagates to parent
#   3. User sees: "SubAgent 'researcher' needs approval for 'internet_search'"
#   4. User approves
#   5. Parent resumes, which resumes SubAgent
#   6. SubAgent completes and returns result

Architecture

Main Agent
  │
  ├─ task("research task", "researcher")
  │   │
  │   └─ SubAgent (as SubAgentServer process)
  │       ├─ Fresh conversation
  │       ├─ Specialized tools
  │       ├─ LLM executes
  │       └─ Returns final message only
  │
  └─ Receives result, continues

HITL Interrupt Flow

1. SubAgent hits HITL interrupt
2. SubAgentServer.execute() returns {:interrupt, interrupt_data}
3. Task tool receives interrupt
4. Task tool returns {:interrupt, enhanced_data} to parent
5. Parent agent propagates to AgentServer
6. User approves
7. Parent agent resumes
8. Task tool calls SubAgentServer.resume(decisions)
9. SubAgent continues and completes