Build an agent map of subagents from configurations.

Build a registry of subagents, raising on error.

Build descriptions map for subagents.

Check if SubAgent can be executed.

Only SubAgents with status :idle can be executed.

Check if SubAgent can be resumed.

Only SubAgents with status :interrupted can be resumed.

Compose the child agent's base_system_prompt from a Config.

Composition rule:

• Header = system_prompt_override (if set) else the built-in boilerplate.
• Body = instructions (if set) else system_prompt (legacy) else "".

The header and body are joined with a blank line. Middleware-contributed prompt fragments are appended later by the normal Sagents.Agent compile path — this function does not handle those.

Execute the SubAgent.

Runs the LLMChain until:

• Natural completion (no more tool calls)
• HITL interrupt (tool needs approval)
• Error

Returns updated SubAgent struct with new status.

Options

• :callbacks - Map of LLMChain callbacks (e.g., %{on_message_processed: fn...})

Examples

case SubAgent.execute(subagent) do
  {:ok, completed_subagent} ->
    result = SubAgent.extract_result(completed_subagent)

  {:interrupt, interrupted_subagent} ->
    # interrupted_subagent.interrupt_data contains action_requests

  {:error, error_subagent} ->
    # error_subagent.error contains the error
end

# With callbacks for real-time message broadcasting
callbacks = %{
  on_message_processed: fn _chain, message ->
    broadcast_message(message)
  end
}
SubAgent.execute(subagent, callbacks: callbacks)

@spec extract_middleware_module(any()) :: module() | nil

Extract the module from any middleware format.

Returns the middleware module regardless of whether the input is:

• A raw module atom
• A {module, opts} tuple
• A MiddlewareEntry struct

Returns nil for unrecognized formats.

Extract result from completed SubAgent.

For completed SubAgents, extracts the final message content as a string. This is the default extraction - middleware or custom logic can provide different extraction.

Returns {:ok, string} on success or {:error, reason} on failure.

Examples

{:ok, completed_subagent} = SubAgent.execute(subagent)
{:ok, result} = SubAgent.extract_result(completed_subagent)
# => {:ok, "Research complete: Solar energy has shown..."}

@spec is_subagent_middleware?(any()) :: boolean()

Check if a middleware spec refers to the SubAgent middleware.

Handles all middleware formats: raw modules, tuples, and MiddlewareEntry structs.

Check if SubAgent is in a terminal state.

Terminal states are :completed and :error.

Create a SubAgent from compiled agent (pre-built).

A compiled subagent is pre-defined by the application with complete control over configuration.

Options

• :parent_agent_id - Parent's agent ID (required)
• :instructions - Task description (required)
• :compiled_agent - Pre-built Agent struct (required)
• :initial_messages - Optional initial message sequence (default: [])
• :parent_tool_context - Parent's tool_context map to inherit (optional). Static, caller-supplied data (e.g., user_id, feature flags) that tools access as flat top-level keys on context. Defaults to %{}.
• :parent_metadata - Parent's state metadata map to inherit (optional). Dynamic, middleware-managed data (e.g., conversation_title) that tools access via context.state.metadata. Defaults to %{}.
• :parent_runtime - Parent's state.runtime map to inherit (optional). Process-local middleware state such as captured ProcessContext snapshots. Inherited so sub-agents continue to see the parent's propagated tenant / OTel / Sentry context. Defaults to %{}.
• :scope - Scope struct to inherit from the parent (optional). Propagated to the SubAgent's custom_context.scope so sub-agent tools and persistence callbacks see the same tenant context as the parent. Defaults to compiled_agent.scope.

Examples

subagent = SubAgent.new_from_compiled(
  parent_agent_id: "main-agent",
  instructions: "Extract structured data",
  compiled_agent: data_extractor_agent,
  initial_messages: [prep_message],
  parent_tool_context: %{user_id: 42},
  parent_metadata: %{"conversation_title" => "Extraction"}
)

Create a SubAgent from configuration (dynamic subagent).

The main agent configures a subagent through the task tool by providing:

• Instructions (becomes user message)
• Agent configuration (Agent struct)

Options

• :parent_agent_id - Parent's agent ID (required)
• :instructions - Task description (required)
• :agent_config - Agent struct with tools, model, middleware (required)
• :parent_tool_context - Parent's tool_context map to inherit (optional). Static, caller-supplied data (e.g., user_id, feature flags) that tools access as flat top-level keys on context. Defaults to %{}.
• :parent_metadata - Parent's state metadata map to inherit (optional). Dynamic, middleware-managed data (e.g., conversation_title) that tools access via context.state.metadata. Defaults to %{}.
• :parent_runtime - Parent's state.runtime map to inherit (optional). Process-local middleware state such as captured ProcessContext snapshots. Inherited so sub-agents continue to see the parent's propagated tenant / OTel / Sentry context. Defaults to %{}.
• :scope - Scope struct to inherit from the parent (optional). Propagated to the SubAgent's custom_context.scope so sub-agent tools and persistence callbacks see the same tenant context as the parent. Defaults to agent_config.scope.

Examples

subagent = SubAgent.new_from_config(
  parent_agent_id: "main-agent",
  instructions: "Research renewable energy impacts",
  agent_config: agent_struct,
  parent_tool_context: %{user_id: 42, tenant: "acme"},
  parent_metadata: %{"conversation_title" => "Research"},
  scope: %MyApp.Accounts.Scope{user: user}
)

Resume the SubAgent after HITL interrupt.

Takes human decisions and continues execution from where it left off. This is the magic - the agent state is already paused at the right spot.

Parameters

• subagent - SubAgent with status :interrupted
• decisions - List of decision maps from human reviewer
• opts - Optional keyword list with:
  • :callbacks - Map of LLMChain callbacks (e.g., %{on_message_processed: fn...})

Returns

• {:ok, completed_subagent} - Execution completed
• {:interrupt, interrupted_subagent} - Another interrupt (multiple HITL tools)
• {:error, error_subagent} - Resume failed

Examples

decisions = [
  %{type: :approve},
  %{type: :edit, arguments: %{"path" => "safe.txt"}}
]

case SubAgent.resume(interrupted_subagent, decisions) do
  {:ok, completed_subagent} ->
    result = SubAgent.extract_result(completed_subagent)

  {:interrupt, interrupted_again} ->
    # Another interrupt - repeat the process

  {:error, error_subagent} ->
    # Handle error
end

@spec subagent_middleware_stack(list(), list(), keyword()) :: list()

Build a middleware stack for subagents, filtering out blocked middleware.

The SubAgent middleware itself is ALWAYS filtered out to prevent recursive subagent nesting, regardless of whether it appears in the block list.

This function handles middleware in all formats:

• Raw module atoms (e.g., Sagents.Middleware.SubAgent)
• Raw tuples (e.g., {Sagents.Middleware.SubAgent, opts})
• Initialized MiddlewareEntry structs (from agent.middleware)

Options

• :block_middleware - List of middleware modules to exclude from inheritance. These modules will not be passed to general-purpose subagents. Defaults to [].

Examples

# Default behavior: only SubAgent middleware is filtered
subagent_middleware_stack(parent_middleware)

# Block additional middleware from being inherited
subagent_middleware_stack(parent_middleware, [],
  block_middleware: [ConversationTitle, Summarization]
)

# Add additional middleware while blocking others
subagent_middleware_stack(parent_middleware, [CustomMiddleware],
  block_middleware: [ConversationTitle]
)

Returns the universal framing prompt prepended to every task-style sub-agent's system prompt.

Encodes the "no user, complete-or-fail, no clarifying questions" contract so that Sagents.SubAgent.Task authors can focus their instructions/0 on the substantive procedure. Host compilers combine this with the task's instructions/0 to form the child agent's system prompt; it can be replaced per-sub-agent via Sagents.SubAgent.Config's system_prompt_override.