---
title: "04 — Sub-agent Use"
description: "## The core idea"
section: ai-docs
raw: "04-sub-agents.md"
source: ai-generated
tags: ai, llama.cpp, docker
last-updated: 2026-09-15
---

# 04 — Sub-agent Use

> Delegating sub-tasks from a large "brain" model to a small "worker" model — the spec→code pattern, and why it beats one big model doing everything.

## The core idea

A single large model handling an entire multi-step task has a structural problem: everything it does — planning, tool calls, intermediate outputs, final answer — accumulates in one context window, and the model's attention degrades as that window fills. **Sub-agents split the job**: the main model decomposes the task and delegates discrete, self-contained sub-tasks to another model endpoint. The sub-agent runs in a **fresh context** (it sees only the task prompt, not the conversation), does the work, and returns only a compact result.

Two consequences make this powerful:

- **Context isolation.** The main model's window stays clean; only the sub-agent's *summary* comes back. This is what lets a main agent run long, tool-heavy conversations without degrading.
- **Model matching.** Each sub-task gets the model that fits it — a big model for design decisions, a small fast model for mechanical work. You pay big-model tokens only where you need big-model quality.

## The spec→code pattern

The local setup uses this pattern for code generation, and it's the clearest demonstration of the idea:

```text
Main agent (big card: 12B/27B, 185k–256k ctx)
   │  designs the solution — requirements, edge cases, structure
   ▼
SPEC (a written specification in the main model's context)
   │  delegated as a self-contained prompt
   ▼
Worker (small card: 4B, 8k ctx, 2 parallel slots)
   │  turns the spec into code — mechanical, well-specified work
   ▼
CODE ──► returned to the main agent for review
```

Why the worker can be a small model here: the *thinking* already happened in the spec. The worker isn't reasoning about design — it's translating a precise description into code, a task a 4B at Q6_K does well. A 9B that only had ~4k context for the whole job (system prompt + tools + spec + output) performed **worse** than a smaller model with 16k — context working memory, not raw parameter count, is what a worker needs.

## Why the worker model has its own card

The sub-agent design reinforces the [primary/secondary split](/ai-docs/03-primary-vs-secondary/): the worker runs on the small card so that generating code (which can be slow and context-hungry at the token level) **never steals context from the main agent's conversation**. With `parallel = 2` on the worker, the main agent can even delegate two independent sub-tasks concurrently — research A and research B running side by side, both reporting back.

## Practical guidance

- **Make sub-task prompts self-contained.** The sub-agent has *no* access to the parent conversation. Everything it needs — task, constraints, relevant file contents, expected output format — must be in the prompt. This is the most common sub-agent failure mode: a vague "fix the thing" prompt with no context.
- **Keep the return contract tight.** Ask for a summary/diff/result, not a transcript. The whole point is that only the compact result re-enters the main context.
- **Delegate, don't do, when a task is 3+ steps of investigation.** A main agent that keeps a long investigation in its own context degrades; the same investigation as a sub-agent finishes cleanly and returns a short answer.
- **Match model to role, and size context for the role.** Spec-writer: big model, big context. Code-writer: small model, ~8k context is plenty (a 4B's useful context is far bigger than its weight class suggests). Embeddings: tiny dedicated model.
- **Disable thinking on mechanical workers.** A reasoning model doing spec→code spends its token budget on `reasoning_content` and may return an empty answer — the design reasoning is already in the spec. Keep thinking enabled only on the model that actually does the design.
- **Parallelise independent sub-tasks.** If the sub-agent server has spare parallel slots (or a spare GPU), independent sub-tasks should run concurrently — that's the throughput win a single-model setup can't give you.

## Where sub-agents sit in the stack

Sub-agents are not a separate component — they are just the application tier calling a *different* inference endpoint and treating the response as a tool result. The main agent's toolset therefore includes "run sub-agent (endpoint X, model Y) with prompt P". Everything from [01 — Architecture](/ai-docs/01-architecture/) (host-gateway addressing, per-server endpoints) applies unchanged.

## Related

- [Primary vs Secondary](/ai-docs/03-primary-vs-secondary/)
- [Context & Quantisation](/ai-docs/02-context-and-quantisation/)
- [Skills](/ai-docs/06-skills/) — reusable, packaged context that makes sub-task prompts consistent

---

## Source Disclaimer

- [x] AI Generated
- [ ] Human Generated
- [x] AI Edited
- [ ] Human Edited