AI agent

Subagent collaboration

Let the main agent spawn subagents — keep context windows from blowing up.

Why subagents exist

An agent's context window is finite — Sonnet 200K, Opus 200K, GPT 128K. When a task needs to read 30 docs and run 20 searches, the main context fills fast, the model starts forgetting earlier content, and logic errors creep in.

Subagents solve this: the main agent delegates a chunk ("read these 30 articles and summarize") to a child with its own fresh context. The child does the work and hands back only the result. The parent never sees the 30 articles — just the summary.

When to use

Research a big topic — subagent gathers, returns a summary
Process 100+ table rows — subagent handles batches
Run independent subtasks in parallel — three concurrent investigations
Isolate permissions — subagent can only read docs/, parent can write
Mix providers — subagent on a cheap model, parent on the strong one

Defining a subagent

A subagent is a Markdown file under .kition/subagents/. The front-matter declares identity and capabilities; the body is the system prompt. The main agent references it by filename.

---
name: research-summarizer
description: Reads articles and returns a structured summary
model: claude-haiku-4
tools:
  - web_fetch
  - Read
  - Write
permissions:
  Write:
    paths: ["scratch/**"]
---

You are a research summarizer. For each URL or file given, produce:

1. **TL;DR** in one sentence
2. **Key claims** as bullets with source line numbers
3. **Open questions** worth digging into

Save your output to scratch/summaries/<slug>.md.
Reply to the parent with just the file path.

How the parent invokes it

The parent calls the subagent tool with name, task, and any context to pass through. The child runs in its own process and returns a result (text plus optional artifact paths).

> tool: subagent
  name: research-summarizer
  task: "Summarize these three papers on retrieval-augmented generation"
  inputs:
    urls:
      - https://arxiv.org/abs/2005.11401
      - https://arxiv.org/abs/2310.11511
      - https://arxiv.org/abs/2401.18059
  result:
    text: "Saved 3 summaries; see scratch/summaries/rag-*.md"
    artifacts:
      - scratch/summaries/rag-original.md
      - scratch/summaries/rag-self.md
      - scratch/summaries/rag-corag.md

Heads up

Cap recursion at 2 — otherwise costs spiral
Free tier allows up to 2 concurrent subagents; Pro lifts the cap
Subagents do not see parent chat history — pass context explicitly
Subagent tool calls go through their own permission set — do not grant writes they should not have
Debug via Settings → Agent → Subagents → Trace for the full call stack

← Back to help center More in AI agent →

Plan mode

For complex tasks: agent drafts a plan → you approve → execution begins.