Agents and Subagents

Every session is driven by a main Agent, which can dispatch sub-agents with isolated context windows. Sub-agents never see the main conversation; only their final result returns. Each sub-agent consumes its own model tokens.

Built-in subagents

Agent	Purpose	Capabilities
`coder` (default)	General-purpose implementation	Read, write, run commands
`explore`	Read-only codebase exploration	Read/search only
`plan`	Planning and architecture	No shell

Built-in sub-agents cannot dispatch further sub-agents. Custom agents inherit a default delegation allowlist (coder, explore, plan); opt into deeper chains with explicit subagents frontmatter.

How subagents are invoked

Automatically by the main Agent — each dispatch shows an approval request unless an allow rule or Ask When Needed mode applies (the Agent tool itself is auto-allowed).
By user instruction: “Use explore to map out the files under src/auth/…”.
Background execution is supported, and existing instances can be resumed (the Agent tool’s resume param). The default subagent timeout is 2 hours ([subagent] timeout_ms, env KIMI_SUBAGENT_TIMEOUT_MS).
“Always allow” rules accepted by the main agent propagate to sub-agents.

The Agent tool and AgentSwarm

Agent — dispatch a single sub-agent (default coder).
AgentSwarm — item-based fan-out: up to 128 subagents, starting at 5 concurrent and ramping +1 per 700 ms; cap via KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY. Auto-allowed in swarm mode; otherwise requires approval in manual mode.
TUI control: /swarm on|off toggles swarm mode; /swarm <task> enables swarm mode and sends the task, auto-turning-off after normal completion.
Persistence: each sub-agent gets its own agents/<id>/wire.jsonl in the session directory; background subagents expose their lifecycle via tasks/.

Custom agents

Custom agents are Markdown files with YAML frontmatter.

Directories (scanned recursively for .md; project root = nearest ancestor with .git):

Scope	Location
User	`$KIMI_CODE_HOME/agents/`, `~/.agents/agents/`
Project	`.kimi-code/agents/`, `.agents/agents/`
Extra	`extra_agent_dirs` in config.toml
Plugin	plugin manifest `agents` field (or plugin-root `agents/`)

Scope priority: Explicit (--agent-file) > Project > Extra > User > Plugin > Built-in. Same-name collisions resolve by scope priority; overriding a same-name built-in requires override: true (not needed for --agent-file).

Frontmatter fields: name (kebab-case; defaults to filename), description (required), whenToUse, override (default false), tools (allowlist; MCP globs like mcp__github__*; omit/* = all; [] = none), disallowedTools, subagents (allowlist; omit = inherit default). The body is the system prompt, rendered as a template with ${var} placeholders such as ${base_prompt}, ${agents_md}, ${cwd}, ${os}, ${shell}, ${skills}.

Example: a read-only reviewer agent

.kimi-code/agents/reviewer.md:

---
name: reviewer
description: Read-only code reviewer for correctness, security, and style issues
whenToUse: Review diffs or recently changed files before merging
tools:
  - Read
  - Grep
  - Glob
---

You are a code reviewer. Read the changed files and their callers, then report
issues ordered by severity: correctness bugs first, then security risks, then
style. Cite every finding as `path:line`. Do not modify any files. If you find
no issues, say so explicitly.

Use it as the main agent for a review-only session:

kimi --agent reviewer
# or
kimi --agent-file ./agents/reviewer.md

Main-agent binding is fixed at session creation (new sessions only; not with --session/--continue); later /new sessions use the default agent. SYSTEM.md can permanently replace the default main agent’s system prompt — see Project Instructions (AGENTS.md).

Subagent model pool (`[secondary_model]`)

Stable since 0.40.0 and enabled by default, this lets subagents run on a different (e.g. faster/cheaper) model than the main agent:

[secondary_model]
default_model = "kimi-for-coding-highspeed"
force = false          # true pins ALL subagents to default_model

TUI: /secondary-model (alias /subagent-model) sets the default subagent model.
The Agent/AgentSwarm tools gain a model param; resolution order: explicit model param > default_model; "primary" means the caller’s model.
Validation failures fail session startup loudly. Disable the pool with KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL=0.

Use cases and limitations

Good fits: read-only codebase mapping (explore), parallel independent work items (AgentSwarm), isolated review passes, cheap-model fan-out via the model pool.

Limitations: sub-agents never see the main conversation (pass everything they need in the dispatch prompt); built-ins can’t chain further sub-agents; each sub-agent burns its own tokens; only the final result returns to the caller.

Last verified: 2026-09-07

Official sources:

AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.