Sub-agents

Sub-agents let a main agent delegate work to specialist agents — each with its own LLM, tools, prompts, and distinct WithName. 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:

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`	Register specialists at creation
`WithMaxSubAgentDepth`	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.

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.

Behavior

Conversation isolation — sub-agents do not inherit the main agent’s conversation ID. They run without session history from the parent.
Independent approval policies — parent and child policies are independent (see Approvals).
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.

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.

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 for the full event reference and approval handling patterns.

Dynamic registration

Add or remove specialists from a running agent via a.SubAgentRegistry() — the next call picks up the updated set with no restart:

math, _ := agent.NewAgent(agent.WithName("Math"), ...)
_ = a.SubAgentRegistry().Register(math)

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

Example

Orchestrator delegating to a math specialist

A2A

Remote agents over the A2A protocol

Approvals

Parent vs specialist approval policies

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Sub-agents

Setup

Behavior

Streaming and STEP events

Dynamic registration

Example

Sub-agents

A2A

Approvals

​Setup

​Behavior

​Streaming and STEP events

​Dynamic registration

​Example

Sub-agents

​Related

A2A

Approvals

Setup

Behavior

Streaming and STEP events

Dynamic registration

Example

Related