Skip to Content
Build AgentsSubagents

Subagents

A subagent is an agent exposed as a tool to another agent. The caller — the coordinator (or supervisor) — decides when to hand off a question to the subagent, receives the subagent’s answer as a tool result, and uses it in its own response.

This lets you build specialized agents (one great at SQL, one great at Slack-drafting, one great at investigation) and have a single entry-point agent dispatch work across them without the user having to pick the right tool.

How it works

When a coordinator has subagents attached, auxilia wraps each subagent as a tool of the coordinator’s graph:

┌──────────────────┐
│  Coordinator     │  ask_sql("top 10 customers by MRR")
│   (LLM + tools)  │ ─────────────────────────────────────┐
└──────────────────┘                                       │
         │                                                 ▼
         │                                      ┌──────────────────┐
         │                                      │  SQL subagent    │
         │                                      │   (LLM + tools)  │
         │                                      └──────────────────┘
         │                                                 │
         │          result                                 │
         │◀────────────────────────────────────────────────┘
         ▼
    final message

Subagents run in their own LangGraph invocation with their own instructions, MCP servers and tool settings; their tool calls, approvals, and messages are rolled up into the coordinator’s stream, and an approval a subagent needs is answered from the coordinator’s thread.

A supervisor and its subagents share one skill set and, when the coordinator is sandboxed, one live sandbox per run — a sandbox-less coordinator can delegate a skill’s script to a subagent with code execution. See Skills.

Constraints

auxilia enforces two structural rules at bind time:

  • An agent that has subagents cannot itself be used as a subagent
  • An agent that is already a subagent cannot have subagents

In other words, the subagent graph is one level deep — no nested coordinators. This keeps reasoning and HITL flows predictable. An agent also cannot be its own subagent, and skill names must be unique across the whole graph.

Managing subagents

Only workspace admins can add or remove subagent links. From an agent’s page:

  1. Click Edit
  2. In the Subagents section, click Add subagent and pick an agent from the workspace
  3. Save changes

Removing a subagent unlinks it; both agents continue to exist.

Picking good subagents

Subagents shine when each one has a narrow, well-described purpose. The coordinator picks between subagents the same way an LLM picks between tools — based on names and descriptions — so:

  • Give each subagent a clear description (it becomes the tool description)
  • Make their instructions specific so they stay on task
  • Bind each subagent to the minimum set of MCP servers it needs
SkillsTriggers