Subagents

A subagent is a focused agent the orchestrator spawns to handle a sub-problem. It inherits the four namespaces but gets a tighter brief, a narrower tool set, and a single explicit return value. Think of them as function calls to other agents.

When the orchestrator delegates

The orchestrator delegates when:

The sub-problem has a known, named workflow. E.g. "research this account" — there's a research_account subagent skilled at the specific sequence of graph walks + summarization.
The sub-problem benefits from parallelism. Three independent pieces of research → three subagents in parallel → one synthesis.
The reasoning shape differs. Drafting a polished email is a different mental motion than reasoning about a pipeline; let a specialist handle it.

The orchestrator does NOT delegate trivial work or one-shot tool calls. Delegation has overhead (assembling fresh context, an additional model round-trip); below a threshold of complexity it's cheaper to do the work inline.

What a subagent inherits

Every subagent boots with:

Inherited	From orchestrator
USER namespace	Identical — same identity, preferences, profile context
TASKS namespace	Identical — pending actions are global to the run
MEMORY namespace	Filtered to relevant subset for the sub-brief
SKILLS namespace	Re-selected for the sub-brief (skill match runs fresh)
Tool set	Narrower — only the tools the subagent's spec lists
Run id, tenant id	Same — telemetry stays correlated

The fresh skill match per subagent is important: a research subagent might pull a different playbook than the orchestrator would. This is the point — specialization.

The brief

When the orchestrator delegates, it emits a structured brief:

{
  "kind": "research_account",
  "input": {
    "account_id": "acc_123",
    "focus": "what's changed in the last 30 days that affects pipeline"
  },
  "output_schema": {
    "summary": "string",
    "key_changes": "string[]",
    "citations": "node_id[]"
  }
}

The output schema is a contract. The subagent's final response is validated against it before being returned to the orchestrator. If the model produces something off-schema, the runtime asks once for a correction; if that fails too, the orchestrator gets a partial result with a warning.

Parallel execution

The orchestrator can spawn multiple subagents in parallel for independent sub-problems:

const [acct_research, content_research, sentiment] = await Promise.all([
  delegate('research_account', { id }),
  delegate('research_content_engagement', { id }),
  delegate('research_sentiment', { id }),
]);

const synthesis = await delegate('synthesize_findings', {
  inputs: [acct_research, content_research, sentiment],
});

The wall-clock cost is max(slowest) not sum(all). For research- heavy tasks this is the biggest single contributor to perceived latency improvement vs a single-agent loop.

Depth limit

Subagents can delegate to deeper subagents — but the platform caps total delegation depth at 3 by default (configurable per tenant). This prevents accidental recursion. Most workflows stay at depth 1 (orchestrator → subagent) or 2 (orchestrator → research → fact- check).

A subagent that tries to exceed the depth cap gets a tool error and must finish at its current depth.

Cost accounting

Every subagent's token usage rolls up to the parent run's totals, labeled by subagent kind. You can see the breakdown in Settings → Agent runs → <run> → Token breakdown. Useful for understanding where the spend goes — a single research_account subagent typically dominates a top-level run that calls it.

The per-tenant LLM spend cap (cloud tier-aware, self-host operator- configurable) covers everything in the tree — there's no "subagent gets its own budget" trick.

Selfhost note

The selfhost agent loop runs the SAME orchestrator + subagent pattern as cloud, with one constraint: tool-calling quality varies by model. Llama 3.1 8B handles the orchestrator's delegate-and-merge pattern reliably; smaller models (Phi-3, Mistral 7B) sometimes flake on long delegation chains. The platform detects flakes (subagent returns malformed structured output 3x in a row) and downgrades to inline reasoning for that subagent kind on subsequent runs. See Self-host hardware.

Available subagent kinds

A non-exhaustive sample:

Kind	Brief shape	Typical use
`research_account`	account_id + focus	Pre-meeting brief, QBR prep
`research_contact`	contact_id + focus	Outreach personalization
`summarize_thread`	thread_id	Inbox summarization
`draft_email`	recipient + intent	Outreach + reply drafts
`extract_tasks_from_text`	source_text	Meeting notes → action items
`compare_deals`	deal_ids + axes	Side-by-side deal analysis
`synthesize_findings`	inputs[]	Roll up parallel research
`fact_check`	claims[] + context	Verify before publishing

New subagent kinds land as part of skill promotions: when a recurring pattern emerges from runs, the promotion pipeline can propose a new subagent specification. The active registry is exposed read-only via GET /api/agents/subagents.