spawn_agent — Manual

What it does

Delegates EXACTLY ONE step of your plan to an isolated agent instance with its own tool-calling loop and a clean context window. Returns the sub-agent's complete final response as a tool result.

One plan step = one spawn_agent call. If your plan has three AGENT steps, make three separate calls.

SYNCHRONOUS by default — blocks until the sub-agent fully completes or times out (5 minutes hard limit). With "background": true the call detaches immediately and returns a task_id (bt-...); the sub-agent keeps running in isolation — see the tasks manual for list/check/wait/cancel, and PARALLELISM rules in your persona. Background sub-agents are capped separately (tasks_max_spawn per session) and their token usage is reported via task_update, not in your turn's token count.

When to use it — and when not

Use it when a step needs 3+ tool calls to complete as one logical unit: a research question that takes several searches and reads, an ops task that chains SSH commands, an investigation with an unknown number of steps.

Do not use it for a single tool call. If the step is "read this file", "run this test", "check whether the service is up" — call the tool yourself. A sub-agent costs a whole extra agent run and gives you back only its final text.

The sub-agent also gets a different, narrower tool set than you have (see Sub-agent tools) and cannot see this conversation. If the step needs a tool the sub-agent will not have, or needs what you have already learned, do it yourself.

Choosing profile_id

Omit it by default. The sub-agent then runs as the current session's profile — the right choice for most work, and the one that keeps its tools closest to yours.

Set it to specialise:

• server_admin — remote ops over SSH, server state, infrastructure.
• secretary — research and writing, web-heavy work.
• tool_developer — implementing Navi tools and MCP servers.

If your plan named a profile for this step, pass that exact id. The profile decides the sub-agent's model, system prompt and available tools — a wrong pick shows up as the sub-agent lacking what it needs.

{"task": "...", "briefing": "..."}                                  // current profile
{"task": "...", "profile_id": "server_admin", "briefing": "..."}    // specialised

Parameters

Sub-agent system prompt structure

The sub-agent receives a completely separate system prompt — no persona, no orchestrator instructions, no available-profiles block. It is built from up to three parts (separated by ---):

1. profile.subagent_system_prompt   ← focused executor persona (from subagent_system_prompt.txt)
2. system_prompt param              ← role specialisation (if provided)
3. ## Task context\n\n{briefing}    ← credentials, instructions (if briefing provided)

Fallback: if the profile has no subagent_system_prompt.txt, uses profile.system_prompt.

Sub-agent tools

Sub-agents receive a dedicated, focused tool set (defined in subagent_tools in profile config):

spawn_agent is always excluded — recursion is impossible.

Result format

The result always starts with a header visible only to you (never repeat it to the user):

• [Sub-agent completed ...] — finished normally; synthesise the findings.
• [Sub-agent hit iteration limit ...] — may be incomplete; note what's missing.

Multi-agent execution pattern

Plan step 2 → AGENT  →  spawn_agent(task="Research pricing for X ...", briefing="...")
Plan step 3 → AGENT  →  spawn_agent(task="Research pricing for Y ...", briefing="...")
Plan step 4 → SELF   →  synthesise both results, write final answer

Wrong: spawn_agent(task="Research X and Y and compare") — two steps, one call.

Full example

{
  "task": "Check CPU temperature and memory usage. Return a table: metric, value, unit, status (ok/warn/crit). Complete ALL assigned work before responding. Your output is final.",
  "briefing": "Host: 192.168.1.10\nUser: ops\nPassword: <ssh-password>\nUse ssh_exec. Check temperature via 'sensors' or /sys/class/thermal/thermal_zone*/temp (divide by 1000). Check memory via 'free -h'.",
  "profile_id": "server_admin",
  "system_prompt": "You are a system metrics collector. Report all values in a structured table with columns: metric, value, unit, status."
}

After the result arrives

The user cannot see sub-agent output — present findings yourself.

1. If "hit iteration limit" — note what is missing in your response.
2. Synthesise key findings in your own words.
3. If result is insufficient, spawn again with a more focused task.

What the sub-agent cannot do

• Spawn further sub-agents (recursion blocked)
• Access conversation history (only context from the current call)
• Use: todo, switch_profile, list_profiles, email_manager, delete_tool, list_tools, tool_manual