# How Subagents Function with the LaborMarket Registry and SubagentStore Persistence in Kimi CLI

> Explore how Kimi CLI subagents interact with the LaborMarket registry for on-demand instantiation and SubagentStore for persistent state management. Learn how this enables seamless recovery.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: internals
- Published: 2026-07-22

---

**The Kimi CLI orchestrates subagents through the LaborMarket registry, which instantiates agent types on demand, while SubagentStore persists each agent's state to disk, enabling seamless recovery across CLI sessions.**

The MoonshotAI/kimi-cli repository implements a sophisticated subagent architecture that separates agent instantiation from state management. This design relies on two core components: the **LaborMarket** registry, which acts as a factory for agent types, and the **SubagentStore**, which handles durable persistence. Understanding how these systems interact is essential for building resilient AI workflows that survive CLI restarts.

## LaborMarket Registry Architecture

Located in [`src/kimi_cli/soul/agent.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py), the **LaborMarket** maintains an internal `registry` dictionary mapping agent type strings to concrete Python classes. When a user requests a new subagent via an **AgentLaunchSpec**, the registry instantiates the appropriate class and injects runtime dependencies including the session, logger, and available toolsets.

The registry decouples agent implementation details from the orchestration layer. By looking up the `type` field in the `AgentLaunchSpec`, the LaborMarket can construct specialized agents such as `ShellAgent` or `ToolAgent` without the calling code needing to import those classes directly.

## SubagentStore Persistence Mechanism

The **SubagentStore** class, defined in [`src/kimi_cli/subagents/store.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/subagents/store.py), manages the lifecycle of agent data on disk. It creates isolated directories under `<session>/subagents/<agent_id>/` and maintains a [`manifest.json`](https://github.com/MoonshotAI/kimi-cli/blob/main/manifest.json) file containing the launch specification and context pointers.

When a subagent executes, the store writes the complete **context** from [`src/kimi_cli/soul/context.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py) along with metadata and **artifact files**. This separation allows the registry to remain stateless while the store handles durability, ensuring that agent progress survives unexpected CLI terminations.

## The Subagent Lifecycle

### Creation and Registration

When the `Runtime` receives a request to create a subagent, it delegates to `LaborMarket.create_agent()`. After construction, the agent ID is immediately registered with the `SubagentStore`, which writes the initial manifest to `<session>/subagents/<agent_id>/manifest.json` and prepares the storage directory for subsequent state writes.

### Runtime Integration and State Saving

During execution, subagents periodically trigger `store.save_state()` to serialize their current context. This method, implemented around lines 64-112 of [`store.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/store.py), flushes the agent's working memory and any generated artifacts to disk.

Because persistence occurs after each significant operation, the system maintains crash resilience without requiring explicit user checkpoints.

### Cross-Session Recovery

Upon startup, `Runtime` initializes `SubagentStore` for the current session and calls `store.list_ids()` to discover persisted agents. For each ID found, the system invokes `store.load(id)`, which reconstructs the agent instance by retrieving the stored spec and hydrating the context from [`src/kimi_cli/soul/context.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py).

This process effectively resurrects subagents exactly where they left off, including their conversation history and intermediate files.

## Working with Subagents: Code Examples

The following examples demonstrate how to interact with the LaborMarket registry and SubagentStore persistence layer programmatically.

Launch a new subagent by constructing an `AgentLaunchSpec` and passing it to the LaborMarket:

```python
from kimi_cli.subagents.core import AgentLaunchSpec
from kimi_cli.soul.runtime import Runtime

runtime = Runtime(session_path="~/.kimi/sessions/2024-09-01")
spec = AgentLaunchSpec(
    type="ShellAgent",          # Must match a type registered in LaborMarket

    name="my-shell",
    args={"cmd": "ls -R"}      # Agent-specific arguments

)

# LaborMarket creates the agent and SubagentStore registers it

subagent = runtime.labor_market.create_agent(spec)

```

Retrieve a previously persisted subagent using the store's loading mechanism:

```python
from kimi_cli.subagents.store import SubagentStore
from kimi_cli.soul.runtime import Runtime

runtime = Runtime(session_path="~/.kimi/sessions/2024-09-01")
store = SubagentStore(runtime.session)

# List all stored sub-agents

ids = store.list_ids()                     # e.g. ["agent-1234", "agent-5678"]

my_agent = store.load("agent-1234")        # Restores the full Agent instance

```

Manually trigger persistence when custom save points are required:

```python
subagent_id = subagent.agent_id
runtime.subagent_store.save_state(subagent_id)   # Flushes context & artifacts to disk

```

## Summary

- The **LaborMarket** registry in [`src/kimi_cli/soul/agent.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py) acts as a factory that maps `AgentLaunchSpec` types to concrete agent classes, injecting runtime services during instantiation.
- **SubagentStore** in [`src/kimi_cli/subagents/store.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/subagents/store.py) provides durable persistence by serializing agent context and metadata to `<session>/subagents/<agent_id>/manifest.json`.
- Agents transition through a lifecycle of creation, registration, periodic state saving via `save_state()`, and automatic recovery through `list_ids()` and `load()`.
- This architecture decouples agent construction from storage, enabling crash resilience and multi-session support where each Kimi session maintains isolated subagent states.

## Frequently Asked Questions

### How does LaborMarket determine which agent class to instantiate?

The LaborMarket maintains an internal dictionary registry that maps string type identifiers to Python classes. When `create_agent()` receives an `AgentLaunchSpec`, it extracts the `type` field and performs a lookup to retrieve the corresponding class constructor.

### What data does SubagentStore actually persist to disk?

The store persists the agent's **context** (conversation state and working memory), the original **launch specification**, creation metadata, and any **artifact files** generated during execution. All data is written as JSON and flat files under the session-specific `subagents/<agent_id>/` directory.

### Can subagents survive a complete CLI restart or system reboot?

Yes. Because `SubagentStore` writes state to disk immediately after tool execution, a complete restart allows `Runtime` to reconstruct all previously running agents by loading their manifests from the session directory and hydrating their contexts via `store.load()`.

### Where can I find the CLI commands to manage subagents interactively?

The command-line interface for creating, listing, and deleting subagents is implemented in `src/kimi_cli/tools/agent/`. These tools wrap the underlying `LaborMarket` and `SubagentStore` APIs, exposing commands like `/agent:create` and `/agent:list` to the user.