Skip to main content
An agent can spawn sub-agents to delegate work to independent child sessions. Each sub-agent gets its own LLM session and tool access, runs concurrently with the parent, and returns its result when finished.
Sub-agents are only available with the API backend (the default). Agents using the ACP backend cannot spawn Fabro sub-agents.

​
Tools

Sub-agent management is exposed through four built-in tools: These tools are registered automatically when the session starts. They inherit the parent’s permissions.

​
Session isolation

Each sub-agent runs in its own session:
  • Own conversation — the child starts with a fresh LLM history
  • Own tool access — the child can use the same tools as the parent
  • Concurrent execution — the parent can continue working before calling wait
The parent can spawn multiple sub-agents and synchronize with them later.

​
Depth limits

Sub-agents can themselves spawn sub-agents, creating a hierarchy. max_subagent_depth limits how deep that tree can grow. By default the depth limit is 1. If a child tries to exceed the limit, spawn_agent returns an error immediately.

​
Error handling

Sub-agent failures do not automatically fail the parent stage. The parent receives the failure through wait and decides how to respond. Common cases:
  • Panics or errors — returned as a failed wait result
  • spawn_agent fails — returned immediately as a tool result

​
Event forwarding

Sub-agent observability now uses session linkage, not wrapper events. Parent-owned lifecycle events: Forwarded child activity:
  • Child tool calls, assistant messages, warnings, and other non-noisy session events are forwarded into the parent run’s event stream as normal agent events.
  • The forwarded event keeps the child’s session_id.
  • parent_session_id points to the child’s immediate parent session.
Example envelope:
Nested sub-agents preserve the immediate parent-child relationship. A grandchild forwarded through multiple parents still carries its own session_id, and parent_session_id remains set to the grandchild’s direct parent rather than the root. High-volume streaming events such as text deltas and tool output deltas are filtered out of the forwarded stream to reduce noise.

​
When to use sub-agents

Sub-agents are most useful for:
  • Parallel research — inspect multiple code paths at once
  • Isolation — try a risky approach without polluting the parent’s context
  • Divide and conquer — split an independent task into smaller pieces
  • Context management — offload work when the parent session is getting crowded
Use child runs instead when the delegated work should be a separate Fabro run with its own workflow, lifecycle, sandbox, checkpoints, and outputs.
Sub-agents run until they complete, fail, are cancelled, or hit the session’s wall-clock timeout. All active sub-agents are cleaned up automatically when the parent session closes.