# What Is agent-core in MoonshotAI/kimi-code? The TypeScript Engine Powering Kimi AI

> Discover agent-core, the TypeScript engine in MoonshotAI/kimi-code. Learn how this library powers autonomous AI agents with its runtime engine, skill management, and more.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: deep-dive
- Published: 2026-08-14

---

**agent-core is the foundational TypeScript library in the MoonshotAI/kimi-code repository that implements the runtime engine for autonomous AI agents, providing a turn-based execution loop, skill management system, and dependency injection infrastructure.**

This package serves as the backbone of the Kimi AI platform, exposing a stateless, test-driven core that higher-level packages like `node-sdk`, `kap-server`, and `klient` consume to build AI-driven tooling. Located at `packages/agent-core`, it exports its public API through [`src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/index.ts) while keeping implementation details modularized across functional domains.

## Core Responsibilities of agent-core

The package orchestrates agent behavior through several specialized subsystems. The architecture is deliberately stateless between turns, with all mutable state managed via dependency-injection (DI) containers to ensure reproducibility.

### Turn-Based Execution Loop

The engine implements a deterministic **turn-based execution loop** centered on the `runTurn` function in [`src/loop/run-turn.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/loop/run-turn.ts). This loop orchestrates LLM calls, schedules tool executions via [`src/loop/tool-scheduler.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/loop/tool-scheduler.ts), handles retries with exponential backoff, and manages streaming responses through [`src/loop/tool-call.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/loop/tool-call.ts). Each turn is atomic and reproducible, allowing sessions to be snapshotted or replayed for debugging.

### Skill System Management

agent-core parses, registers, and executes **skills** through modules in `src/skill/`. The [`registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/registry.ts) file maintains the skill catalog and lookup mechanisms, while [`parser.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/parser.ts) processes skill definitions (typically YAML front-matter) and [`scanner.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/scanner.ts) discovers built-in and custom skills at runtime. This system enables dynamic extension of agent capabilities without modifying core engine code.

### Hierarchical Lifecycle Scopes

The library defines strict **lifecycle scopes**—App → Workspace → Session → Agent—each with its own DI container. This hierarchy isolates configuration and state management across different granularity levels. Workspace-level services reside in [`src/services/workspace/workspaceRegistry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/services/workspace/workspaceRegistry.ts), which acts as the DI container for workspace-specific instances, while session state persists through injectable `SessionStore` services.

### MCP Configuration and OAuth

The **MCP (multi-client-provider)** subsystem in `src/mcp/` centralizes configuration management. The [`global-config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/global-config.ts) module handles global and per-workspace settings, while the `oauth/` directory manages token handling and server-side authentication flows. This configuration layer allows different workspaces to maintain separate provider credentials and server endpoints.

### Telemetry and Error Handling

Structured logging flows through [`src/logging/logger.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/logging/logger.ts), which provides standardized log sinks across the engine. Typed error codes and serialization utilities live in `src/errors/`, while the feature-flag system in [`src/flags/registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/flags/registry.ts) and [`src/flags/resolver.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/flags/resolver.ts) enables safe rollout of experimental capabilities and A/B testing of agent behaviors.

## Architectural Overview

The package organizes functionality into distinct layers that higher-level SDKs compose into complete applications:

- **Core Engine** (`src/loop/*`): Houses [`run-turn.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/run-turn.ts), [`tool-scheduler.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/tool-scheduler.ts), and [`tool-call.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/tool-call.ts) for execution management.
- **Skill System** (`src/skill/*`): Contains [`registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/registry.ts), [`parser.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/parser.ts), and [`scanner.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/scanner.ts) for skill operations.
- **DI Services** (`src/services/*`): Provides injectable containers for workspace registry, session stores, and provider management.
- **Configuration** (`src/mcp/*`): Manages global MCP settings, OAuth tokens, and workspace-specific configs.
- **Infrastructure** (`src/flags/*`, `src/logging/*`, `src/errors/*`): Supports feature gating via the flags registry, structured logging, and typed error serialization.

Because the engine maintains no state between turns, parallelizing sessions or implementing distributed execution requires only spinning up additional DI container instances.

## Working with agent-core

While most developers interact with agent-core through the `node-sdk`, you can import types directly from the core package to build custom implementations.

### Installation

Install the core package directly:

```bash
pnpm add @moonshot-ai/agent-core

```

Or use the SDK which bundles and configures agent-core automatically:

```bash
pnpm add @moonshot-ai/node-sdk

```

### Basic Implementation Example

The following example demonstrates creating a session and executing a turn using the SDK, which internally wires the agent-core engine:

```typescript
// demo.ts
import { createKimiHarness } from '@moonshot-ai/node-sdk'
import { Config } from '@moonshot-ai/agent-core'

// 1. Configure workspace and model defaults
const cfg: Config = {
  workspace: { root: '/tmp/kimi-workspace' },
  model: { default: 'gpt-4o-mini' },
}

// 2. Initialize harness (wires AgentCore DI containers)
const harness = await createKimiHarness({ config: cfg })

// 3. Create isolated session context
const session = await harness.createSession({ name: 'demo-session' })

// 4. Execute turn (core loop handles LLM call and tool scheduling)
await session.sendMessage({ 
  role: 'user', 
  content: 'Explain the concept of dependency injection.' 
})
await session.runTurn()

// 5. Retrieve conversation transcript
const transcript = await session.transcript()
console.log(transcript.map(m => `${m.role}: ${m.content}`).join('\n'))

```

The `createKimiHarness` function in [`packages/node-sdk/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/index.ts) instantiates the agent-core engine, configures the hierarchical DI containers, and returns a harness that manages the App → Workspace → Session lifecycle automatically.

## Key Source Files

Understanding the entry points and critical modules helps when extending or debugging the engine:

- **[`packages/agent-core/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/index.ts)**: Public export barrel and entry point for the `@moonshot-ai/agent-core` package.
- **[`src/loop/run-turn.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/loop/run-turn.ts)**: Core turn execution logic including LLM invocation, tool scheduling, and retry handling.
- **[`src/skill/registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/skill/registry.ts)**: Skill registration, lookup, and loading mechanisms for built-in and custom skills.
- **[`src/mcp/global-config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/mcp/global-config.ts)**: Global MCP configuration read/write operations and default value management.
- **[`src/services/workspace/workspaceRegistry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/services/workspace/workspaceRegistry.ts)**: Workspace-level DI container implementation and service registry.
- **[`src/logging/logger.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/logging/logger.ts)**: Structured logger interface used across all engine subsystems.
- **[`src/flags/registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/flags/registry.ts)**: Feature-flag registry for gating experimental agent capabilities.
- **`src/errors/*.ts`**: Typed error codes, error classes, and serialization utilities.

## Summary

- **agent-core** is the foundational TypeScript runtime engine for Kimi AI agents, located at `packages/agent-core` in the MoonshotAI/kimi-code repository.
- It provides a **stateless, turn-based execution loop** via [`src/loop/run-turn.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/loop/run-turn.ts) that manages LLM calls, tool scheduling, and retry logic.
- The **skill system** in `src/skill/` enables dynamic registration and execution of custom commands and prompts parsed from YAML definitions.
- **Hierarchical DI containers** manage scoped state across App, Workspace, Session, and Agent lifecycles, with registries defined in `src/services/`.
- The **MCP subsystem** handles multi-provider configuration and OAuth flows, while structured logging and typed errors provide production-grade observability.

## Frequently Asked Questions

### What is agent-core in MoonshotAI/kimi-code?

agent-core is the foundational TypeScript library that powers the Kimi AI agent platform. It provides the runtime engine for autonomous agents, including a turn-based execution loop, skill management system, dependency injection infrastructure, and MCP configuration handling. Higher-level packages like `node-sdk` import `@moonshot-ai/agent-core` to leverage its test-driven engine without reimplementing agent lifecycle management.

### How does the turn-based execution loop work in agent-core?

The loop is implemented in [`src/loop/run-turn.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/loop/run-turn.ts) and operates deterministically to process each interaction turn. It orchestrates LLM API calls, schedules tool executions via the tool scheduler, manages streaming responses, and implements retry logic for transient failures. Because the engine maintains no state between turns, all context persists through DI-provided services like `SessionStore`, making turns atomic and reproducible.

### What is the skill system in agent-core?

The skill system is a modular framework in `src/skill/` that parses, registers, and executes custom agent capabilities. The [`registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/registry.ts) module maintains the skill catalog, [`parser.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/parser.ts) processes YAML front-matter definitions, and [`scanner.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/scanner.ts) discovers available skills at runtime. This architecture allows developers to extend agent behavior with custom commands and prompts without modifying the core engine source code.

### Can I use agent-core independently of the Kimi node-sdk?

Yes, you can import `@moonshot-ai/agent-core` directly to build custom agent implementations, though most developers use the `node-sdk` wrapper for simplified configuration. Direct usage requires manual instantiation of the DI containers and management of the lifecycle scopes (App → Workspace → Session → Agent) that the SDK typically handles automatically via the `createKimiHarness` function.