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. AskUserQuestion middleware is excluded - A subagent has no user to ask. Its :ask_user_question interrupt is raised from inside a tool body, so it returns to the parent wrapped as :subagent_hitl with the question buried where the question-rendering path does not look. The task-subagent system prompt already states "You cannot ask the user questions. There is no user in this conversation.", so inheriting the ask_user tool handed the subagent a capability the prompt then had to police.

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

Exclusions apply to inheritance only. A pre-configured subagent that names one of these in its own :middleware list still receives it.

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
]}

Suppressing Debug Events

A sub-agent's events are published on the parent's :debug channel, and they carry content: the initial messages, every inner LLM message live, and the whole inner chain on failure or cancellation. For a sub-agent that exists as a confidentiality boundary — it reads sensitive data and is meant to return only a narrow result — set :suppress_debug_events on its config:

{SubAgent, [
  model: model,
  subagents: [
    SubAgent.Config.new!(%{
      name: "pii-extractor",
      description: "Extract structured fields from a sensitive document",
      tools: [extract_tool],
      suppress_debug_events: true
    })
  ]
]}

Nothing about that sub-agent's run reaches the parent's :debug channel. The parent still receives the outcome as the task tool result; only the observer fan-out is silenced. Defaults to false, so existing consumers are unaffected.

The setting is per sub-agent type and all-or-nothing. It does not apply to the general-purpose sub-agent, which is created dynamically rather than declared in :subagents and so has no config to carry the flag.

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

Halts are propagated, not wrapped

The flow above applies to interrupts that can be resolved: a HITL approval, a question. A :halt is different. It declares the workflow over, so there is nothing to approve and nothing to resume.

When a sub-agent tool emits %{type: :halt} (or a :multiple_interrupts batch containing one, since "halt wins"), the halt is propagated to the parent as a halt rather than wrapped in :subagent_hitl, and the sub-agent process is stopped. This is what lets the parent's existing halt machinery apply: the loop terminates without another LLM call, Sagents.Middleware.Haltable claims the interrupt for cold-start restore, and Sagents.AgentUtils.interrupt_session_changes/1 surfaces the halt's author-facing :message.

The propagated halt keeps the emitting tool's :source_tool and gains a :source_task naming the sub-agent that ran it. It deliberately carries no :sub_agent_id, because a restorable interrupt must be pure data and the sub-agent process does not survive a reboot.