#Subagents

The Agent tool delegates large or context-heavy subtasks to subagents that run in isolated sessions: each child sees only the prompt you pass it (never the parent conversation) and returns only its final text. Isolation keeps the parent's context clean — you get the answer without paying for the exploration that produced it.

#Declaring a subagent

A subagent is an agents/*.md file with YAML frontmatter; the body becomes the subagent's system prompt:

---
name: researcher
description: Research a topic and report findings with sources
tools: [read_file, bash]   # optional allow-list; absent = inherit the parent's tools
model: claude-haiku-4-5    # optional modelName override (same provider)
---

You are a research agent. Always cite your sources ...

Loading order (later directories override earlier ones by name):

1. Global: ~/.lite-agent/agents
2. Project: <workdir>/.lite-agent/agents
3. agentsDir config option, if set

A built-in general-purpose agent (inherits the parent's full tool set and model) is always seeded, so subagents work with zero files. Set agents: false to disable the whole capability.

#Dispatch

One Agent call takes a batch of tasks; entries in a single call run in parallel (bounded concurrency), and each result block is labeled with an agentId that can be passed back as resume to continue that subagent later:

{
  "tasks": [
    { "subagent_type": "researcher", "prompt": "Compare Rspress and VitePress" },
    { "subagent_type": "general-purpose", "prompt": "Audit deps for vulnerabilities" }
  ]
}

By default the call blocks until all children finish; run_in_background: true makes it fire-and-forget, with the aggregated results delivered later as a <background-task-completed> notification.

#Programmatic access

Use AgentLoader / builtinAgents directly if you need the same loading mechanism outside createLiteAgent.

#See also

• Built-in tools — the Agent tool and how to disable it (agents: false).
• Skills — the other markdown-driven, on-demand capability.
• Permissions — write the allow/deny rules subagentPermission expects.
• Custom tools — add tools your subagents can inherit.