Iteration 9: Subagents (Background Tasks)

[carletex]

Goal

Spawn isolated agents for long-running tasks. Bot messages you back on Telegram when done. Main agent stays responsive.

When to use subagents

The main agent decides per-request via prompt instructions:

• Quick/simple (single tool call, direct answer) → handle directly
• Long/complex (multi-step research, many tool calls) → spawn subagent

Concepts

• Main agent spawns a subagent via spawn tool
• Subagent runs in background with its own mini agent loop
• Limited tool access (no spawn, no message sending — prevents recursion)
• Lower max iterations (e.g. 15)
• On completion, result sent back to user via Telegram
• Context isolation: subagent has its own context, only final summary comes back

Use cases

• "Research X and get back to me" — deep research without blocking chat
• "Summarize all articles from this feed" — multi-step fetching
• Parallel work: quick question answered immediately, deep task runs in background

Tasks

• src/agent/subagent.ts — SubagentManager class
  • spawn(task, onComplete) — starts background agent, returns task ID
  • Mini agent loop with limited tools and max iterations
• src/tools/spawn.ts — Spawn tool
  • Takes task description param
  • Returns task ID to the main agent
• Callback mechanism: onComplete sends result back to user's Telegram chat
• Prompt instructions for when to spawn vs handle directly

Acceptance criteria

• "Research X and get back to me" → bot spawns subagent, responds with task ID
• Subagent completes → bot sends result as new Telegram message
• Simple questions still answered directly (no unnecessary subagent)
• Subagent can't spawn other subagents (no recursion)
• Subagent errors don't crash the main agent