> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenticenv.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-agents

> Register specialist sub-agents and configure delegation depth and approval policies

Sub-agents let a **main agent** delegate work to **specialist agents** — each with its own LLM, tools, prompts, and distinct [`WithName`](/getting-started/configuration). The main agent sees each specialist as a delegation tool the LLM can invoke.

When delegation fires, the runtime determines how it runs:

* **Temporal** — the specialist runs as a **child workflow** on its task queue.
* **Restate** — the specialist is an independent agent (own `AgentLoop` service and listen port); the parent invokes that service and stream events fan in to the parent's event log.
* **Local runtime** — it executes in-process.

In all cases, the sub-agent result is fed back as a tool result to the main agent's LLM for the next round.

Use sub-agents for domain specialists (math, research, coding) without concentrating every capability into one prompt and tool list. Sub-agents also let you apply different models, system prompts, and tool policies per domain.

## Setup

Build each specialist with `NewAgent`, then register it on the main agent:

```go theme={null}
mathAgent, err := agent.NewAgent(
    agent.WithName("math-specialist"),
    agent.WithDescription("Arithmetic; uses calculator tools."),
    temporal.WithTemporalConfig(&temporal.TemporalConfig{
        Host: "localhost", Port: 7233, Namespace: "default",
        TaskQueue: "my-app",
    }),
    agent.WithLLMClient(llmClient),
    agent.WithToolRegistry(mathTools),
    agent.WithToolApprovalPolicy(agent.AutoToolApprovalPolicy()),
)
if err != nil {
    return err
}
defer mathAgent.Close()

mainAgent, err := agent.NewAgent(
    agent.WithName("orchestrator"),
    agent.WithSystemPrompt("You are a helpful assistant."),
    temporal.WithTemporalConfig(&temporal.TemporalConfig{
        Host: "localhost", Port: 7233, Namespace: "default",
        TaskQueue: "my-app",
    }),
    agent.WithLLMClient(llmClient),
    agent.WithSubAgents(mathAgent),
    agent.WithMaxSubAgentDepth(2),
)
if err != nil {
    return err
}
defer mainAgent.Close()

agentRun, err := mainAgent.Run(ctx, "What is 144 divided by 12?", nil)
if err != nil {
    return err
}
result, err := agentRun.Get(ctx)
```

| Option | Description |
| - | - |
| [`WithSubAgents`](/getting-started/configuration) | Register specialists at creation |
| [`WithMaxSubAgentDepth`](/getting-started/configuration) | Max delegation nesting depth — default **2** |

Sub-agent names must differ from the root. Use clear `WithName` and `WithDescription` values — they appear in the delegation tool schema the LLM sees for routing decisions.

<Note>
  Each delegation is a tool round on the **main agent** — it consumes one iteration from `WithMaxIterations`. An orchestrator that delegates twice and then generates a final answer uses at least 3 iterations. With the default of 5, headroom is tight. Increase `WithMaxIterations` on the main agent to match your expected delegation depth: a good starting point is `2 × expected delegations + 2`.
</Note>

## Behavior

* **Conversation isolation** — sub-agents do not inherit the main agent's conversation ID. They run without session history from the parent.
* **Budget** — when a parent agent has [`WithBudget`](/features/budget), nested sub-agent token and cost usage counts toward the **parent** run. A child's own `WithBudget` applies only when that agent is run on its own.
* **Worker pairing** — with `DisableLocalWorker`, pair each `NewAgentWorker` with the same options as the `NewAgent` it runs.
* **Validation at build** — sub-agent graphs are validated for cycles and depth violations at `NewAgent`. Errors fail fast.

<Warning>
  Sub-agents do **not** share the parent's conversation history. If you need the specialist to have context from the parent session, include it in the delegation prompt or tool call arguments.
</Warning>

## Streaming and STEP events

Subscribe once on the main agent — sub-agent events fan in to the same channel. When the specialist actually runs, the parent stream emits `STEP_STARTED` and `STEP_FINISHED` events with `StepName` set to the specialist's `WithName` value. `STEP_FINISHED` fires whether the child run succeeded or failed.

Tool events, approval requests, and `RUN_FINISHED` from each level all appear on the main stream. See [Streaming](/getting-started/streaming) for the full event reference and approval handling patterns.

## Dynamic registration

Add or remove specialists from a running agent via [`a.SubAgentRegistry()`](/advanced/dynamic-capabilities) — the next call picks up the updated set with no restart:

```go theme={null}
math, _ := agent.NewAgent(agent.WithName("Math"), ...)
_ = a.SubAgentRegistry().Register(math)

// revoke later
_ = a.SubAgentRegistry().Unregister("Math")
```

## Example

<CardGroup cols={2}>
  <Card title="Sub-agents" icon="play" href="/examples/subagents" horizontal>
    Orchestrator delegating to a math specialist
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="A2A" icon="network-wired" href="/features/a2a" horizontal>
    Remote agents over the A2A protocol
  </Card>

  <Card title="Approvals" icon="shield-check" href="/features/approvals" horizontal>
    Parent vs specialist approval policies
  </Card>

  <Card title="Budget" icon="gauge" href="/features/budget" horizontal>
    Parent budget covers nested sub-agent usage
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.