spawn_agent — Manual

What it does

Delegates a focused multi-step sub-task 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.

CRITICAL: spawn_agent is SYNCHRONOUS. It blocks until the sub-agent fully completes. When the call returns, the work is done. There is no background process.

Parameters

• task (string, required) — what the sub-agent must accomplish, including success criteria and expected output format
• briefing (string) — all context from the current conversation the sub-agent needs
• profile_id (string) — which profile to use (secretary, server_admin, smart_home); defaults to current session's profile
• max_iterations (integer) — tool-call iteration limit (default: 20)

Before you spawn: write a plan

For any task involving multiple sub-agents, state the plan in your response first:

Plan:
1. Agent A — audit network exposure on host X
2. Agent B — check auth config on host Y (independent of A)
3. Agent C — cross-reference findings from A and B → needs A and B results first

This prevents wasted spawns, wrong ordering, and missed dependencies.

Writing a good task

Bad:

"Check the server security."

Good:

"Audit SSH configuration on the server. Check: PasswordAuthentication, PermitRootLogin, AllowUsers, Port, key-only auth enforcement. Return a list of findings with severity (critical/warning/info) and suggested fix for each."

Include:

• Exactly what to do (not vague goals)
• What to return and in what format
• What "done" looks like

Writing a good briefing

The sub-agent knows nothing. Include everything it needs:

• Host IPs/hostnames, SSH credentials, API endpoints, tokens
• File paths to read or write
• Prior findings it should build on
• Any constraints or things to avoid

End every briefing with:

"Complete ALL assigned work before responding. Your output is final."

Choosing a profile

After the result arrives

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

1. Read the result fully before deciding what to do next.
2. Extract the key findings and present them clearly.
3. Decide if another spawn is needed based on what you received, not assumptions.
4. If the result is incomplete or unclear, either spawn again with a corrected task or handle it inline.

What the sub-agent cannot do

• Spawn further sub-agents (recursion is blocked)
• Access your conversation history
• Persist sessions or memory across calls

Example

{
  "task": "Read tools/get_current_datetime.py and tools/user_notes.py. For each file report: purpose, any external dependencies, potential security issues. Return as a structured list per file.",
  "briefing": "Project root is /home/user/Projects/navi-1. Both files are small user-defined tools. No credentials needed — filesystem access is unrestricted.\n\nComplete ALL assigned work before responding. Your output is final.",
  "profile_id": "secretary"
}