Subagents
Delegate a self-contained task to an autonomous subagent with its own context window — it works in isolation and returns one tight report, so the main thread never fills up with exploration.
A subagent is a fresh agent spawned to complete one self-contained task in isolation. It has its own context window, runs the full agent loop with its own tools, and returns a single condensed report — its transcript and tool output never enter the parent thread. This keeps the main conversation focused: a big investigation ("map how auth works across these 12 files") happens in the subagent's window, and only the answer comes back.
Subagents are driven by the built-in task tool, so the model spawns them on its own when a job is worth isolating — and you can ask for one explicitly ("spawn an explorer to map the render pipeline").
Built-in agent types
Each type is a role with a tailored system prompt and a tool allowlist. general is the default.
| Type | Role | Access |
|---|---|---|
explorer | Map and explain a codebase region — trace call sites, cite exact file:line | read-only |
reviewer | Critically review code/changes — bugs, edge cases, races, security; prioritised findings | read-only |
tester | Reproduce, run, and diagnose — build/run tests, report root cause with the failing assertion | read + run (no prod edits) |
coder | Implement a change end-to-end, verify it builds | read + write |
general | Complete any delegated task with whatever tools fit (default) | full toolset |
Read-only types (explorer, reviewer) are physically prevented from writing files, running commands, or reaching the network — the sandbox rejects any tool with a write/exec/net effect, so a review can't accidentally mutate your tree.
✦TipFan out. Because each subagent is isolated, the model can launch several in parallel — three explorers over three subsystems — and merge their reports, without any of them polluting each other's or the parent's context.
Custom agent types
Drop a Markdown file in .agentty/agents/ (project) or ~/.agentty/agents/ (all projects). The body is the role's system prompt; optional frontmatter configures its sandbox:
---
description: Reviews SQL migrations for safety. # shown in the catalog
tools: read grep glob list_dir # optional allowlist (space-separated)
read-only: true # optional effect gate
---
Your role: MIGRATION REVIEWER. Check every migration for destructive
operations, missing transactions, and non-idempotent DDL. Report each
issue with the file and line and a safer rewrite.| Field | Meaning |
|---|---|
description | one-line summary for the subagents catalog and the task tool's type list |
tools | space-separated allowlist — the agent may use only these tools (omit for all) |
read-only | true blocks every write/exec/net tool, exactly like explorer/reviewer |
| (body) | the role prompt the subagent runs under |
The file name (without .md) is the type name you pass as agent_type. Search roots, project first: .agentty/agents, .agents/agents, .claude/agents, then the same three under your home directory. Built-ins always win — a general.md can't silently replace the built-in general. Files are picked up live (no restart); up to 32 custom agents, 32 KiB each.
ℹNoteA persona defined in a project .agentty/agents/ can ride in on a cloned repo, and its role prompt steers a subagent that wields real (sandboxed) tools. That's a lower risk than a plugin — an agent names no command, its tools stay gated, and it runs only when invoked — so it isn't blocked, just surfaced: the task card tags a project-defined agent as project agent so an injected persona is never invisible. Built-in and your own ~/.agentty agents show no tag. See Plugin Trust.
Managing subagents in the app
Ctrl+K → Subagents lists the built-in types and every custom agent it discovered, and can drop a starter template into .agentty/agents/ to author from. Authoring is a file you edit; the panel is for browsing what's available.
How a subagent runs
- Isolated & autonomous. It never sees the parent conversation and can't ask it questions — it works from the task prompt alone, makes a reasonable assumption on ambiguity (and notes it), then stops and writes a tight, evidence-cited report. The report is the only thing the parent receives.
- Bounded, per role. Each subagent runs a capped burst — 8 K output tokens, tool results clipped, and a turn budget sized to the work: 32 turns for read-only roles (explorer, reviewer), 80 for write roles (coder, tester, general). A read sweep converges quickly; an implementation loop is read → edit → build → read the errors → fix → re-run, which is several turns per cycle and several cycles per task. These are ceilings, not quotas — an agent that finishes in five turns costs five. Everything stays comfortably inside the base 200 K window, so a fan-out stays cheap. It never uses the 1M-context beta.
- Prompt-cached. The heavy shared prefix (system prompt + tool schemas + accumulated results) is cached across the subagent's turns, keyed per role + task, so a long investigation doesn't re-pay for its prefix every turn.
- Gated twice. A role only sees the tools it's allowed, and a call to any other tool is refused when it arrives, so a read-only role can't write even if the model names a tool it wasn't offered.
- Same prompt rules as the main turn. On a model you run yourself (a local or LAN server), a subagent gets the short local-model prompt the main turn uses, with its "do the work with tools, don't refuse a big task" rules. See Providers › The prompt local models get.
- Rate limits. A short rate limit is retried up to 3 times, waiting what the provider asks for (at most 30 s). If the provider says to wait more than 15 minutes, that's a quota, and the subagent stops and reports it instead of waiting.
agentty run is this same loop with your prompt as the task, so everything here applies to it too. See agentty run.
Model routing
By default, read-only roles (explorer, reviewer) are routed to the cheapest capable model your active provider offers — mapping, reading, and reviewing are grunt work a small model does well — while write-capable roles (coder, tester, general) keep the parent model so their edits match its quality. The router never routes up and never crosses providers, so a single-model or Opus-only account sees no change.
With Smart Mode subagent routing enabled, each worker's model is resolved by its role through your pinned model slots instead (explorer → Utility, reviewer → Strategic, coder/tester/general → Implementation).
Related
- Smart Mode — role-based routing that decides which model each subagent runs on.
- Tools — the tools a subagent can be allowed.
- Sandboxing & permissions — how read-only enforcement and tool gating work.