Kimi CLI Agents Explained: Built-in, Custom, Subagents, and Tools

This post is a walkthrough of Kimi CLI's agent system — how agents, system prompts, subagents, and built-in tools fit together. Below is a structured English summary of the original Chinese post.

Key points

• What agents are: In Kimi CLI, an agent defines AI behavior via a system prompt, a set of tools, and subagents. Agents are selected with --agent (e.g., kimi --agent okabe).
• Built-in agents:
• default: enables Task, SetTodoList, Shell, ReadFile, ReadMediaFile, Glob, Grep, WriteFile, StrReplaceFile, SearchWeb, FetchURL (plus Think).
• okabe (experimental): same as default plus SendDMail, intended for testing new prompts and tool combinations. SendDMail sends delayed messages (D-Mail) to a checkpoint ID, useful for checkpoint rollback scenarios.

Custom agents (YAML)

• Loaded via kimi --agent-file /path/to/my-agent.yaml.
• Structure: version: 1, then an agent block with name, system_prompt_path (Markdown template), tools (format module:ClassName, e.g. kimi_cli.tools.shell:Shell), and optional subagents.
• Inheritance: the extend field inherits another agent (e.g., extend: default), then overrides fields or uses exclude_tools (e.g., to drop SearchWeb/FetchURL). Relative paths can reference other custom agent files. system_prompt_args are merged on inheritance.

System prompt templates

• Markdown templates using ${VAR} syntax. Built-in variables:
• ${KIMI_NOW} — current time (ISO format)
• ${KIMI_WORK_DIR} — working directory path
• ${KIMI_WORK_DIR_LS} — directory file listing
• ${KIMI_AGENTS_MD} — AGENTS.md content if present
• ${KIMI_SKILLS} — loaded skills list
• Custom variables via system_prompt_args, e.g. MY_VAR: "custom value" referenced as ${MY_VAR}.

Subagents

• Defined in a subagents block with path (relative) and description (e.g., a coder and a reviewer). Subagent files are themselves YAML, typically extending the main agent and excluding the Task tool to avoid nesting loops.
• The main agent invokes them via the Task tool with description, subagent_name, and prompt. Subagents run in isolated contexts (own conversation history), enabling context isolation, parallelism, and focused prompts. The prompt must contain all needed information.
• CreateSubagent (not enabled by default) lets the AI define new subagent types at runtime with name and system_prompt.

Built-in tools

• Task: dispatch subagents (3–5 word description, subagent name, detailed prompt).
• SetTodoList: todo list with titles and pending/in_progress/done statuses.
• Shell: run commands (requires approval); timeout default 60s, max 300s; uses bash/zsh or PowerShell depending on OS.
• ReadFile: text files, limited to 1000 lines / 2000 chars per read; absolute paths outside working directory.
• ReadMediaFile: images/video up to 100MB, model-dependent.
• Glob: pattern matching (e.g., *.py), max 1000 items, not allowed as prefix.
• Grep: regex content search with glob/type filters, output modes (e.g., files_with_matches), context flags (-B/-A/-C), -n line numbers, -i case-insensitive, multiline, head_limit.
• WriteFile: write files (approval required), overwrite or append mode.
• StrReplaceFile: string-replacement editing (approval required), with old/new and replace_all.
• SearchWeb: web search (requires configuration), limit default 5 max 20, optional content inclusion.
• FetchURL: fetch a URL and return main text.
• Think: record reasoning thoughts.
• SendDMail: delayed message to a checkpoint_id (>= 0).

Safety boundaries

• Tool operations are confined to the working directory; outside paths require absolute paths.
• Writing, editing, Shell execution, and MCP calls require per-user-approval** each time.
• Limits on file sizes, line counts, and Glob prefixes prevent resource abuse and over-broad searches.