Sub-agents

A lead agent can hand work to other agents in two ways. By the end of this page you will have run both, found every child’s trace from the lead’s, and put a person in front of a delegation.

	Explicit sub-agents	Spawned workers
You write	`sub_agents=[researcher, coder]`	`agent_config={"enable_subagents": True}`
The lead gets	one tool per child: `delegate_researcher`, `delegate_coder`	one tool: `spawn_subagents`
Who the children are	agents you built, with their own instructions, tools and settings	workers the model describes on the spot: a name, a role, a task, an output file
Results come back as	the child’s answer, as the tool result	a file in the workspace, which the lead reads, and each worker’s answer as a `summary` (up to 500 characters) in the tool result
Use it when	the team is known and each member has its own tools	the split depends on the task, or parts can run in parallel

Every output on this page is what the code printed when it was run with gpt-5.4-mini. The model’s wording, the tasks it writes for its children, and whether it calls them one after the other or together, will differ on your run.

A fixed team

Each agent in sub_agents becomes a delegate_<name> tool on the lead. The lead’s model decides when to call it and what to ask.

import asyncio
from omnicoreagent import OmniCoreAgent, ToolRegistry

research_tools = ToolRegistry()

@research_tools.register_tool("country_facts")
def country_facts(country: str) -> dict:
    """Look up facts about a country."""
    return {"country": country, "capital": "Lisbon", "population_millions": 10.6}

MODEL = {"provider": "openai", "model": "gpt-5.4-mini"}

researcher = OmniCoreAgent(
    name="researcher",
    system_instruction="You look facts up with your tools. Answer in plain text.",
    model_config=MODEL,
    local_tools=research_tools,
)
coder = OmniCoreAgent(
    name="coder",
    system_instruction="You write short Python snippets. Reply with the code only, no markdown fences.",
    model_config=MODEL,
)
lead = OmniCoreAgent(
    name="manager",
    system_instruction=(
        "You manage a researcher and a coder. Get the facts from the researcher first; "
        "only when you have them, give them to the coder. Answer in plain text, without markdown."
    ),
    model_config=MODEL,
    sub_agents=[researcher, coder],
)

async def main():
    tools = await lead.list_all_available_tools()
    print("lead's delegation tools:", [t["name"] for t in tools if t["name"].startswith("delegate_")])

    result = await lead.run(
        "Find Portugal's capital and population, then get one line of Python that prints them."
    )
    print(result["response"])

    trajectory = await lead.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            print("step", step["step"], "->", call["tool_name"], call["arguments"], call["outcome"])

    family = await lead.get_trace_family(trace_id=result["trace_id"])
    names = {trace["trace_id"]: trace["agent_id"] for trace in family}
    for trace in family:
        print("trace:", trace["agent_id"], "| parent:", names.get(trace["parent_trace_id"]))

    for agent in (lead, researcher, coder):
        await agent.cleanup()

asyncio.run(main())

lead's delegation tools: ['delegate_researcher', 'delegate_coder']
Portugal’s capital is Lisbon, and its population is about 10.6 million.

print("Portugal's capital is Lisbon and its population is about 10.6 million.")
step 1 -> delegate_researcher {'query': "Find Portugal's capital and population. Return the capital and a population figure with source context if possible. Keep it concise.", 'tags': ['geography', 'population'], 'provenance': {'user_request': 'Portugal capital and population'}} success
step 2 -> delegate_coder {'query': "Write one line of Python that prints Portugal's capital and population using: capital = Lisbon, population = about 10.6 million. Make it a single print statement.", 'tags': ['python', 'formatting'], 'provenance': {'source': 'researcher_result', 'capital': 'Lisbon', 'population': 'about 10.6 million'}} success
trace: manager | parent: None
trace: researcher | parent: manager
trace: coder | parent: manager

What happened:

The lead’s model called delegate_researcher, then passed what it learned to delegate_coder. A delegate_<name> tool takes the parameters of the child’s run(): query (the task, required), and optional tags and provenance, which are recorded on the child’s trace.
Each child ran as a whole agent run of its own — its own tools, its own trace — with the lead’s session_id and a new run_id.
get_trace_family returned the lead’s trace and both children’s, each child naming its parent in parent_trace_id. The lead’s trajectory also nests each child’s trajectory under the call that started it (call["subagent"]["child_trajectory"]).

With the first wording of this instruction (“ask the researcher, then the coder”), the model called both children in the same step — independent calls in one step run together — and the coder wrote placeholders. Say so in the lead’s instruction when one child needs another’s answer.

Workers spawned on demand

With enable_subagents, the lead gets a spawn_subagents tool and writes the workers itself:

import asyncio
from omnicoreagent import OmniCoreAgent

async def main():
    lead = OmniCoreAgent(
        name="planner",
        system_instruction=(
            "You split work across workers with spawn_subagents, then read their "
            "output files and combine them. Answer in plain text, without markdown."
        ),
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        agent_config={"enable_subagents": True},
    )
    result = await lead.run(
        "In parallel, have one worker write three tips for a first trip to Kyoto and "
        "another write three tips for a first trip to Lisbon. Then give me one line per city."
    )
    print(result["response"])

    trajectory = await lead.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            if call["tool_name"] == "spawn_subagents":
                for spec in call["arguments"]["subagents"]:
                    print("spawned:", spec["name"], "->", spec["output_path"])
            else:
                print("step", step["step"], "->", call["tool_name"], call["arguments"])

    family = await lead.get_trace_family(trace_id=result["trace_id"])
    print("traces:", [trace["agent_id"] for trace in family])
    await lead.cleanup()

asyncio.run(main())

Kyoto: Start sightseeing early to beat crowds, use a prepaid transit card, and bring cash for smaller places.

Lisbon: Wear comfortable shoes for the hills, get a Viva Viagem transit card, and visit popular sights early to avoid crowds.
spawned: kyoto_tips -> kyoto_tips.txt
spawned: lisbon_tips -> lisbon_tips.txt
step 2 -> read_file {'path': 'kyoto_tips.txt'}
step 3 -> read_file {'path': 'lisbon_tips.txt'}
traces: ['planner', 'subagent_kyoto_tips', 'subagent_lisbon_tips']

Both workers ran in parallel from one spawn_subagents call, each wrote its file (workspace/files/kyoto_tips.txt and lisbon_tips.txt), and the lead read them before answering. The model sends the tool a subagents list — one item for one worker, up to 15 for parallel work:

{"subagents": [
  {
    "name": "api",
    "role": "API reviewer",
    "task": "Review API error handling and write concrete risks.",
    "output_path": "/workspace/product_audit/subagent_api/output.md"
  },
  {
    "name": "tests",
    "role": "Test reviewer",
    "task": "Review coverage gaps and write recommended test cases.",
    "output_path": "/workspace/product_audit/subagent_tests/output.md"
  }
]}

All four fields are required. A leading /workspace/ in output_path means the agent’s workspace files folder.

Worker profiles: the right model for each worker

A worker that only searches does not need your strongest model, and one that only reviews should not write. List the kinds of worker the lead may start in worker_profiles, and the lead picks one for each worker, by its description:

from omnicoreagent import OmniCoreAgent

lead = OmniCoreAgent(
    name="lead",
    system_instruction="Plan the work, delegate it, and check the results.",
    model_config={"provider": "openai", "model": "gpt-5.4"},
    agent_config={
        "enable_subagents": True,
        "worker_profiles": [
            {
                "name": "explorer",
                "description": "Reads and searches the workspace; never edits.",
                "model_config": {"model": "gpt-5.4-mini"},
                "reasoning_effort": "low",
                "tools": ["read_file", "grep", "glob", "ls"],
                "max_steps": 20,
            },
            {
                "name": "builder",
                "description": "Writes and tests code.",
                "reasoning_effort": "high",
                "policy": {"ask": [{"capability": "workspace.files.delete"}]},
            },
        ],
    },
)

With profiles set, every worker names one: spawn_subagents takes a profile for each worker, and its description lists each profile with its model, effort, steps and tools. A worker with no profile, or one not listed, starts nothing, and the lead is told the names. Without profiles, workers are as described below.

Profile key	Default	What it does
`name`	required	What the lead names: lowercase letters, digits, `_` and `-`.
`description`	required	What the lead reads to choose this kind of worker.
`model_config`	the lead’s	Laid over the lead’s. With the same provider (or none given) the rest, the key among it, comes from the lead’s; with another provider it is used whole, and the lead’s key is not sent.
`reasoning_effort`	the lead’s	`none`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`.
`tools`	all of the lead’s	The only tools the worker is offered; `write_file` is always kept, for its output.
`mcp_servers`	all of the lead’s	The only MCP servers the worker gets, by name.
`policy`	none	`deny` and `ask` rules added before the lead’s; `allow` is refused. Needs governance on.
`max_steps`	the smaller of the lead’s and 50	1 to 50, and never more than the lead’s.
`instructions`	none	Added to the worker’s system prompt, after its role and task.

A profile only narrows: a tool or MCP server the lead does not have is refused when the lead initializes, and a worker never gets an allow rule its lead does not have. Every worker spends the lead’s budgets, whatever its model. Each spawn records the profile, model and effort the worker ran with, and the subagent.spawn request names the profile, so a policy can, for example, ask before any builder starts. A runnable example is cookbook/getting_started/agent_with_worker_profiles.py.

How it works

What a spawned worker gets. A worker, named subagent_<name>, inherits (unless its profile says otherwise) the lead’s model, MCP servers, your local tools, and its whole agent_config — workspace files, skills, the sandbox, context management and tool offloading — with these changes: at most 50 steps, no spawn_subagents of its own, and workspace files, context management and offloading always on. Its system instruction is its role, its task, and the file to write. Output goes to files, not the lead’s context, so it survives the lead’s context being trimmed. What enable_subagents changes on the lead. It turns workspace files, context management and tool offloading on — keeping any budget, threshold and strategy you set — because the lead reads its workers’ files and must not run out of context doing it. Time. A delegate_<name> call is a tool call: it is bounded by tool_call_timeout (180 seconds by default). spawn_subagents is not: a worker is bounded by its own step cap and the run’s deadline, and by subagent_timeout if you set it. Evidence. Every child’s trace is linked to the lead’s: find them with get_trace_family(trace_id=...) or get_trace_family(run_id=...), or read them nested in the lead’s trajectory. The lead’s trace records subagent_spawn, subagent_result and subagent_error events.

Governance

When the lead has governance on, every delegation is a subagent.spawn request, decided by the lead’s policy. The development profiles (interactive-dev) ask for it, so the run pauses before any child starts:

import asyncio
from omnicoreagent import OmniCoreAgent

MODEL = {"provider": "openai", "model": "gpt-5.4-mini"}
GOVERNED = {"governance_config": {"enabled": True, "profile": "interactive-dev"}}

async def main():
    translator = OmniCoreAgent(
        name="translator",
        system_instruction="You translate English to French. Reply with the translation only.",
        model_config=MODEL,
        agent_config=GOVERNED,
    )
    lead = OmniCoreAgent(
        name="desk",
        system_instruction="Delegate translations to the translator. Answer in plain text.",
        model_config=MODEL,
        sub_agents=[translator],
        agent_config=GOVERNED,
    )
    result = await lead.run("Translate 'the train leaves at noon' into French.")
    print("status:", result["status"])
    while result["status"] == "awaiting_approval":
        for approval in result["approvals"]:
            print("waiting on:", approval["tool_name"], approval["arguments"])
            await lead.resolve_approval(
                result["run_id"], approval["approval_id"], decision="approve", approver="alice"
            )
        result = await lead.resume(result["run_id"])
        print("status:", result["status"])
    print(result["response"])
    await lead.cleanup()
    await translator.cleanup()

asyncio.run(main())

status: awaiting_approval
waiting on: delegate_translator {'query': 'the train leaves at noon'}
status: success
le train part à midi

The rules:

A governed agent only delegates to governed children. A child with no governance_config is governed by default (permissive-dev); a child that turns governance off ({"enabled": False}) is refused — its tools would run under no policy. The child is governed by its own policy, so configure it for the child’s tools.
Spawned workers run under the lead’s policy plus one rule: they cannot spawn workers of their own; a worker’s profile may add deny and ask rules. What they spend counts against the lead’s budgets: one ledger for the lead and all its workers.
A child’s ask pauses the lead. The child’s pending approvals appear on the lead’s run — each naming the child’s call, its arguments, and the child’s run (delegated_run_id) — and the lead’s run goes to awaiting_approval. A decision on the lead’s approval (resolve_approval, or POST /runs/{run_id}/approvals/{approval_id}) is forwarded to the child’s, and when the lead resumes, the child’s run resumes where it stopped rather than starting over.
An ask on the delegation itself, as above, pauses the lead the same way, before any child runs.

See the security model and the policy reference for subagent.spawn.

Options

Where	Setting	Default	What it does
constructor	`sub_agents`	`None`	A list of `OmniCoreAgent`s; each becomes a `delegate_<name>` tool.
`agent_config`	`enable_subagents`	`False`	Gives the lead `spawn_subagents`.
`agent_config`	`worker_profiles`	`[]`	The kinds of worker the lead may start, each with its own model, effort, tools and rules (above).
`agent_config`	`subagent_timeout`	`None`	Seconds one `spawn_subagents` call may take (2–86,400).
`agent_config`	`tool_call_timeout`	`180`	Seconds one tool call may take — including a `delegate_<name>` call.
`agent_config`	`max_steps`	`50`	The lead’s step cap; a spawned worker gets the smaller of this and 50.

Everything else is in the agent settings and OmniCoreAgent references.

When things go wrong

Delegation refused: agent 'translator' is not governed. A governed agent can only delegate to agents with governance enabled.

The lead has governance on and the child turned it off ("governance_config": {"enabled": False}). The call fails with this as its error, and the run carries on — in our run the model simply translated the sentence itself. Leave the child’s governance on: drop {"enabled": False}, or give it a profile or policy of its own.

ValueError: sub_agents must be a list of agents, e.g. sub_agents=[researcher]

sub_agents takes a list, even for one child: sub_agents=[researcher].

ValueError: subagent_timeout must be between 2 and 86400, got 1

subagent_timeout is in seconds, from 2 to 86,400 — or None for no limit beyond the workers’ own.

The lead's run is awaiting_approval and no tool of yours was called

The profile asks before subagent.spawn (both delegate_<name> and spawn_subagents), or a child hit an ask. Approve as above, or allow the capability in your policy; permissive-dev allows it outright.

A worker's output is missing

A worker must write its output_path. When it did not, the lead is told Subagent '<name>' did not create the requested output: <path>. Give the worker a task it can finish within 50 steps, with the tools it inherits.

Context engineering

What keeps the lead and its workers inside their context.

Durable runs

Approvals, pauses and resumes — for delegated runs too.

Observability

Trajectories with every child run nested in.

Security model

What a policy decides, for sub-agents and everything else.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Sub-agents

Sub-agents

A fixed team

Workers spawned on demand

Worker profiles: the right model for each worker

How it works

Governance

Options

When things go wrong

Next

Context engineering

Durable runs

Observability

Security model

​Sub-agents

​A fixed team

​Workers spawned on demand

​Worker profiles: the right model for each worker

​How it works

​Governance

​Options

​When things go wrong

​Next

Context engineering

Durable runs

Observability

Security model

Sub-agents

A fixed team

Workers spawned on demand

Worker profiles: the right model for each worker

How it works

Governance

Options

When things go wrong

Next