diff --git a/manuals/spawn_agent.md b/manuals/spawn_agent.md index ec4d096..57f7b77 100644 --- a/manuals/spawn_agent.md +++ b/manuals/spawn_agent.md @@ -1,8 +1,9 @@ # 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. +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. **CRITICAL: spawn_agent is SYNCHRONOUS.** It blocks until the sub-agent fully completes (or times out after 5 minutes). @@ -10,24 +11,15 @@ | Parameter | Required | Description | |-----------|----------|-------------| -| `task` | yes | What to accomplish: exact goal, success criteria, expected output format. End with: "Complete ALL assigned work before responding. Your output is final." | -| `briefing` | no | All context the sub-agent needs (IPs, credentials, file paths, prior findings, step-by-step instructions). Sub-agent starts blank — include everything. | +| `task` | yes | Goal for this one step, success criteria, expected output format. End with: "Complete ALL assigned work before responding. Your output is final." | +| `briefing` | no | Credentials, IPs, file paths, constraints, step-by-step instructions — injected as system-level context into the sub-agent. | | `profile_id` | no | Which profile to use (`secretary`, `server_admin`, `developer`). Defaults to current session's profile. | -| `system_prompt` | no | Role definition injected on top of the profile's built-in subagent prompt. Use to specialise the agent for this task (e.g. "You are a security auditor. Report findings by severity."). | +| `system_prompt` | no | Role specialisation for this task (e.g. "You are a security auditor. Report findings by severity."). Injected on top of the profile's built-in subagent prompt. | | `max_iterations` | no | Tool-call iteration limit (default: 20). | -## Context transfer — automatic - -Before spawning, write key working state to your scratchpad `context_transfer` section: -``` -scratchpad(op="write", section="context_transfer", content="...") -``` -This section is **automatically injected** into the sub-agent at the start of its context. -Use it to pass findings from earlier tool calls or parallel agents without duplicating them in `briefing`. - ## Sub-agent tools -Sub-agents receive a focused tool set (not all profile tools — no todo, switch_profile, email_manager, etc.): +Sub-agents receive a focused tool set (no todo, switch_profile, email_manager, etc.): | Profile | Sub-agent tools | |---------|----------------| @@ -43,24 +35,24 @@ **Never repeat the result header to the user.** Synthesise findings in your own words. -## Writing a good task + briefing +## Example: correct multi-agent execution -```json -{ - "task": "Check CPU temperature and memory usage. Return a structured table: metric, value, unit, status (ok/warn/crit). Complete ALL assigned work before responding. Your output is final.", - "briefing": "Host: 192.168.1.75\nUser: gmikcon\nPassword: getroot\nUse ssh_exec to connect. Check temperature via 'sensors' or /sys/class/thermal. Check memory via 'free -h'.", - "profile_id": "server_admin" -} +``` +Plan step 2 → AGENT → spawn_agent(task="Research pricing for product X ...", briefing="...") +Plan step 3 → AGENT → spawn_agent(task="Research pricing for product Y ...", briefing="...") +Plan step 4 → SELF → synthesise both results, write final answer ``` -## Using system_prompt for role specialisation +**Wrong:** `spawn_agent(task="Research X and Y pricing and write a comparison")` — two steps, one call. + +## Full example ```json { - "task": "Audit the SSH configuration for security issues.", - "briefing": "Host: 192.168.1.75, user: gmikcon, password: getroot.", + "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.75\nUser: gmikcon\nPassword: getroot\nUse ssh_exec. Check temperature via 'sensors' or /sys/class/thermal. Check memory via 'free -h'.", "profile_id": "server_admin", - "system_prompt": "You are a security auditor. For each finding report: setting name, current value, risk level (critical/warning/info), recommended fix." + "system_prompt": "You are a system metrics collector. Report all values in a structured table." } ``` @@ -74,5 +66,5 @@ ## What the sub-agent cannot do - Spawn further sub-agents (recursion is blocked) -- Access your conversation history (only context_transfer scratchpad section is passed) +- Access your conversation history - Use administrative tools: todo, switch_profile, list_profiles, email_manager, delete_tool diff --git a/navi/profiles/secretary/system_prompt.txt b/navi/profiles/secretary/system_prompt.txt index eab7c60..ce6956b 100644 --- a/navi/profiles/secretary/system_prompt.txt +++ b/navi/profiles/secretary/system_prompt.txt @@ -56,11 +56,9 @@ ### Briefing sub-agents spawn_agent takes three content fields: - `task`: goal for this one step + expected output format + "Complete ALL assigned work before responding. Your output is final." -- `briefing`: static context the sub-agent needs — credentials, file paths, constraints, step-by-step instructions. +- `briefing`: credentials, file paths, constraints, step-by-step instructions for this sub-agent. - `system_prompt`: optional role specialisation (e.g. "You are a data analyst. Return results as a structured table."). -Context transfer: write intermediate findings from prior steps into `scratchpad(section="context_transfer")` before spawning — injected automatically. Credentials and instructions always go in `briefing`, not here. - --- ## Tool priorities diff --git a/navi/profiles/server_admin/system_prompt.txt b/navi/profiles/server_admin/system_prompt.txt index 54131b0..56ea4ab 100644 --- a/navi/profiles/server_admin/system_prompt.txt +++ b/navi/profiles/server_admin/system_prompt.txt @@ -57,11 +57,9 @@ ### Briefing sub-agents spawn_agent takes three content fields: - `task`: what to accomplish in this one step + expected output format + "Complete ALL assigned work before responding. Your output is final." -- `briefing`: static context — hostname/IP, credentials, exact commands or checks to run, constraints. +- `briefing`: hostname/IP, credentials, exact commands or checks to run, constraints. - `system_prompt`: optional role specialisation (e.g. "You are a security auditor. Report findings by severity: critical / warning / info."). -Context transfer: write findings from prior agents into `scratchpad(section="context_transfer")` before spawning — injected automatically. Credentials always go in `briefing`, not here. - ### Scratchpad discipline - `status` — host/service states, versions, resource usage - `logs` — relevant excerpts with timestamps (trim noise aggressively) diff --git a/navi/tools/spawn_agent.py b/navi/tools/spawn_agent.py index 67b306b..0c46d00 100644 --- a/navi/tools/spawn_agent.py +++ b/navi/tools/spawn_agent.py @@ -25,8 +25,6 @@ "USER CANNOT SEE sub-agent output — synthesise findings into your own response.\n\n" "USE when a step requires 2+ tool calls to complete as a single logical unit.\n" "DO NOT USE for a single tool call — call the tool directly.\n\n" - "Context transfer: before spawning, write working state from prior steps into " - "scratchpad(section='context_transfer') — it is injected automatically." ) parameters = { "type": "object", @@ -42,10 +40,8 @@ "briefing": { "type": "string", "description": ( - "Static context injected as a system-level instruction: " - "IPs, credentials, file paths, constraints, step-by-step instructions. " - "For dynamic results from prior steps, use scratchpad(section='context_transfer') " - "instead — it is injected automatically." + "Static context injected as system-level instruction: " + "IPs, credentials, file paths, constraints, step-by-step instructions." ), }, "profile_id": { diff --git a/persona.txt b/persona.txt index 2ad551a..1e43e34 100644 --- a/persona.txt +++ b/persona.txt @@ -28,10 +28,8 @@ spawn_agent fields: - task (required): goal for THIS ONE STEP, success criteria, expected output format. -- briefing (optional): credentials, file paths, step-by-step instructions — injected as system-level context. -- system_prompt (optional): role specialisation (e.g. "You are a security auditor. Report by severity."). - -context_transfer: write findings from prior steps into scratchpad(section="context_transfer") before spawning — injected automatically into the next subagent. Use for intermediate results. Credentials and instructions go in briefing, not here. +- briefing (optional): credentials, file paths, constraints, step-by-step instructions — injected as system-level context into the sub-agent. +- system_prompt (optional): role specialisation for this task (e.g. "You are a security auditor. Report by severity."). End every task field with: "Before each tool call, write one sentence: what you are calling and why. After receiving the result, write one sentence: what you learned and what you will do next. Complete ALL your assigned work before writing your final response. Your output is final."