Agent Flow in Kimi CLI: A Deep Dive into KLIP-10, the Flowchart-Driven AI Agent Experience

Forum topic · ✨步子哥 · 2026-01-31

Summary

KLIP-10 introduces Agent Flow, a new capability for Kimi CLI that lets AI agents execute multi-step workflows defined as flowcharts written in Mermaid or D2 syntax. Instead of responding to single commands, agents follow a structured script: they start at a BEGIN node, execute task nodes as prompts, and navigate decision branches based on labels on edges, until reaching an END node. This article explains the motivation behind Agent Flow, the deliberately minimal grammar subset it supports, its internal Flow data structure and strict validation rules, the FlowRunner engine that orchestrates execution with automatic retry and a max_moves safety cap, and the Ralph mode that auto-generates iterative loops. Flow skills are discovered through the existing Agent Skill mechanism, degrade gracefully to standard skills on parse failure, and are invoked via /flow:<name> slash commands. The post includes an email-assistant example and discusses design trade-offs around backward compatibility and unsupported advanced graph features.

Agent Flow in Kimi CLI: A Deep Dive into KLIP-10

Imagine sitting at a terminal late at night, fingers flying across the keyboard—only to realize you're not writing code, but directing an adventure play for intelligent agents. Every node is a conversation; every branch is a choice of fate. That's the surprise KLIP-10 brings to Kimi CLI: Agent Flow, a new capability that gives AI agents a "script" to follow.

Why Agent Flow? The Origin Story

The old Kimi CLI was like a knight who only obeyed single-sentence commands: you say one thing, it does one thing. For complex tasks, you had to keep typing and re-explaining context. Developers wanted agents that could "read the script themselves"—understanding an entire workflow at once, stepping through nodes, and choosing different paths at critical moments.

KLIP-10 extends Agent Skill into two types:

standard — the traditional skill type
flow — a new type whose core is a flowchart drawn in Mermaid or D2

The flowchart uses BEGIN as the start, END as the finish, with nodes representing prompts and decision branches marked by edge labels. The agent walks from BEGIN to END, node by node.

> Why a flowchart instead of code? > Flowcharts are inherently intuitive. When expressing "do A first, then decide between B or C based on the result," a diagram is often clearer than a pile of if-else statements. Mermaid and D2 are declarative languages that render directly in Markdown—low barrier, yet expressive enough for complex control flow.

The Script Grammar: A Minimal but Elegant Subset

Agent Flow doesn't parse the full Mermaid or D2 grammar—only a carefully chosen subset that covers ~99% of real scenarios:

Mermaid: flowchart TD (top-down) or LR (left-right); nodes with [text], (text), or {text} (shape is purely visual); edges connected with -->; branch labels via -->|yes| or -- yes -->; inline node definitions on edges are supported.

D2: nodes written as ID: label, edges with ->, labels on the final edge segment, comments starting with #, and node IDs supporting letters, digits, underscore, dot, slash, and hyphen.

The agent only needs "who connects to whom, and what the labels are." Ignoring subgraphs, styles, and click events keeps parsing simple and prevents users from accidentally writing "fancy scripts" the agent can't understand.

> A simple example > To have the agent draft an email and ask whether to polish it into a formal tone: > BEGIN → Draft email → Formal tone needed? {yes/no} → Polish / Send directly → END > The agent executes "Draft email," shows you the draft, prompts you at the branch node, and follows your choice automatically.

The Soul of the Graph: Data Structure and Strict Validation

Agent Flow is abstracted as a Flow class containing a node dictionary, outgoing edge lists, start ID, and end ID. Each node has id, label (plain text or rich-text content blocks), and kind (begin, end, task, decision). Edges record source, target, and an optional label.

Validation rules act like a strict director:

Exactly one BEGIN and one END (recognized case-insensitively by node text)
END must be reachable from BEGIN
Nodes with multiple outgoing edges must have non-empty, non-duplicate labels on every edge
Single-outgoing-edge nodes may omit labels (ignored)
Undeclared nodes are auto-created with the ID as the label, supporting common shorthand

Violations raise dedicated exceptions: FlowParseError (syntax) or FlowValidationError (structure), with clear messages and line numbers for quick fixes.

Discovery and Loading: A Dual Identity in the Skill Directory

Agent Flow reuses the existing Agent Skill discovery mechanism—built-in skills, user home directory skills, and project directory skills are all scanned. If a SKILL.md declares type: flow and contains a mermaid or d2 code block, the parser builds a Flow object attached to Skill.flow.

If parsing fails, the system doesn't crash—it silently degrades to a standard skill and logs a message. This ensures backward compatibility without letting one bad diagram break everything.

Standard skills are still invoked via /skill:<name>, while flow skills get a dedicated /flow:<name> entry. These commands are dynamically registered as instance-level slash commands during KimiSoul initialization.

The Heart of the Engine: FlowRunner

FlowRunner is the director, holding the script (Flow object) and guiding the agent (KimiSoul) step by step. For each node:

1. Determine whether branching is needed based on outgoing edge count 2. Build a dedicated prompt: task nodes use the label as the system prompt; decision nodes append the available branch list and require the model to output a <choice> tag at the end of its reply 3. Send the prompt to KimiSoul and get the response 4. For decision nodes, extract the last <choice>...</choice> via regex and match it exactly against edge labels 5. Jump to the next node based on the match

If the model forgets or mis-formats its choice, FlowRunner retries automatically with a reminder appended to the next prompt. A max_moves hard cap (default 1000 steps) prevents infinite loops.

Special Chapter: Ralph Mode's Automatic Loop

Ralph mode is a hidden Easter egg. Launched with --max-ralph-iterations, KimiSoul auto-creates a special loop flow: starting from your initial instruction, it executes → decides (CONTINUE/STOP) → if CONTINUE, loops back to the decision node → until STOP or the iteration limit. The loop is dynamically generated by FlowRunner.ralph_loop—no hand-written flowchart needed. It's ideal for "keep refining until satisfied" scenarios, like iterative code polishing or design refinement.

The Terminal Performance: CLI Integration and UX

No new commands to learn. Write a flowchart into SKILL.md, declare type: flow, restart Kimi CLI, and type /flow:<skill-name> to start. Syntax errors point to exact line numbers; structure errors explain what's missing; choice failures retry automatically. All key events are logged for debugging complex flows.

Boundaries and Compatibility: Elegant Trade-offs

KLIP-10 explicitly does not support subgraphs, styles, links, click events, or the complete Mermaid/D2 grammar. BEGIN and END must use those exact words (case-insensitive); branch labels should be short and stable. Cyclic graphs are allowed but bounded by max_moves. Old skills are unaffected, and failed flow parsing degrades gracefully—everything stays quiet and elegant.

Epilogue: When the Terminal Learns to Tell Stories

The first time the author launched /flow:email-assistant and watched the agent draft, ask about tone, polish, and finally "send," the realization hit: we're no longer just using tools—we're collaborating with an intelligent partner that reads scripts.

Agent Flow turns static prompts into dynamic journeys and one-way commands into two-way interaction. It suggests that the future of AI agents lies not just in stronger models, but in more natural control—like directing a film, not feeding actors lines one by one.

---

References

1. KLIP-10 proposal: Agent Flow (Agent Skill extension). Author: @stdrc, Updated: 2026-01-20. 2. Kimi CLI skill system implementation: https://github.com/MoonshotAI/kimi-cli/tree/main/src/kimi_cli/skill 3. Mermaid flowchart documentation: https://mermaid.js.org/syntax/flowchart.html 4. D2 declarative diagram language: https://d2lang.com/tour 5. Agent Client Protocol discussions (background): https://github.com/agentclientprotocol/agent-client-protocol