# Agent-Core v1 vs v2 Architecture in Kimi Code: A Complete Technical Comparison

> Compare Kimi Code's agent-core-v1 and agent-core-v2 architectures. Discover agent-core-v2s scoped DI engine and four lifecycle layers for production servers.

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

---

**Agent-core-v1 provides a lightweight, single-class model with minimal DI, while agent-core-v2 delivers a scoped DI engine with four lifecycle layers (App → Workspace → Session → Agent) for production server environments.**

Kimi Code, MoonshotAI's AI coding assistant, ships with two distinct core engine architectures. Understanding the difference between agent-core-v1 and agent-core-v2 helps developers choose the right foundation for their use case—whether building a simple CLI tool or deploying a multi-tenant production service.

## Core Architectural Philosophy

The two architectures represent fundamentally opposing design choices.

**Agent-core-v1** prioritizes simplicity and standalone usability. The `Agent` class in `packages/agent-core/src/agent/*` can be instantiated directly with minimal configuration—no `Session` object, `agentId`, or session lifecycle machinery required.

**Agent-core-v2** embraces compositional complexity through dependency injection. As defined in [`packages/agent-core-v2/app/scopes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/app/scopes.ts), the engine organizes resources across four nested scopes, each owning services through the "L3 unit layer" of `Service`/`Fiber` units.

## Key Differences Explained

### Session Handling

| Version | Implementation |
|---------|---------------|
| v1 | **Optional `sessionId` hint only**—the `Agent` receives an optional ID but retains no session state. All metadata lives externally. |
| v2 | **First-class scope integration**—`IWorkspaceLifecycleService.handlerFor` returns handlers pre-bound to concrete `Session` scopes with automatic cleanup and lifecycle hooks. |

### Dependency Injection Model

**v1 (Minimal DI)**
- Plain constructor arguments (e.g., `provider`, optional `sessionId`)
- Immediate instantiation without container overhead
- Direct imports or subclassing for extensions

**v2 (Full DI Container)**
- Container resolution via `#` import alias
- Per-scope service registration and injection
- Plugin-style extensions through `src/features/*`

### Feature Extension Mechanism

In **v1**, extensions require direct helper imports or `Agent` subclassing. The flat architecture trades evolution safety for simplicity.

In **v2**, extensions register as **feature seams** in `packages/agent-core-v2/src/features/*`. Each feature:
- Declares its own services
- Toggles via experimental flags
- Remains isolated from core engine code

### Experimental Flag Handling

**v1 centralizes** flags in [`packages/agent-core/src/flags/registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/flags/registry.ts), accessed through:

```typescript
flags.enabled('my-feature')

```

**v2 distributes** flags to owning domains through `registerFlagDefinition` and `IFlagService.enabled(id)`, keeping definitions adjacent to guarded code per [`packages/agent-core-v2/docs/flag.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/docs/flag.md).

## Code Examples: Architecture in Practice

### Creating a Standalone Agent (v1)

```typescript
import { Agent } from '@moonshot-ai/agent-core';

// Constructor is lightweight—no Session binding
const myAgent = new Agent({
  sessionId: 'demo-session',  // optional hint only
  // provider and other deps
});

await myAgent.run('Explain the difference between v1 and v2');

```

The implementation in `packages/agent-core/src/agent` creates temporary turns internally without session lifecycle coupling.

### Obtaining a Scoped Handler (v2)

```typescript
import { IWorkspaceLifecycleService } from '@moonshot-ai/agent-core-v2';
import { inject } from '#/di';

// Resolve from DI container
const workspaceService = inject<IWorkspaceLifecycleService>('workspaceLifecycle');

// Handler bound to Session scope with full DI support
const handler = await workspaceService.handlerFor('my-workspace', 'session-42');

await handler.run('Explain the difference between v1 and v2');

```

The [`packages/agent-core-v2/app/scopes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/app/scopes.ts) implementation ensures the handler runs within proper cleanup boundaries.

### Registering a Feature Flag (v2)

```typescript
import { registerFlagDefinition } from '@moonshot-ai/agent-core-v2/docs/flag';

registerFlagDefinition({
  id: 'my-new-feature',
  description: 'Enable the new experimental feature',
  default: false,
});

```

Per [`packages/agent-core-v2/docs/flag.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/docs/flag.md), this pattern co-locates flag logic with feature implementation.

## Target Use Cases

| Scenario | Recommended Version | Rationale |
|----------|-------------------|-----------|
| Simple CLI tools, scripts | **v1** | Minimal startup cost, no lifecycle overhead |
| Multi-tenant REST/WebSocket servers | **v2** | Scoped resource management, production isolation |
| Prototype agents | **v1** | Faster iteration without DI ceremony |
| Kimi Code production backend (kap-server) | **v2** | Required for full session lifecycle and feature flags |

## Source File Reference

Critical implementation files referenced in this comparison:

- [`packages/agent-core/AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/AGENTS.md) — v1 design rules and constraints
- `packages/agent-core/src/agent/*` — `Agent` class implementation
- [`packages/agent-core-v2/AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/AGENTS.md) — v2 scoped architecture overview
- [`packages/agent-core-v2/app/scopes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/app/scopes.ts) — four lifecycle scope definitions
- `packages/agent-core-v2/src/features/*` — feature seam implementations
- [`packages/agent-core-v2/docs/flag.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/docs/flag.md) — v2 flag registration patterns

## Summary

- **Agent-core-v1** offers a single-class, minimal-DI model optimized for standalone agents and CLI tools
- **Agent-core-v2** delivers a scoped DI engine with explicit App → Workspace → Session → Agent lifecycle management
- v2's `IWorkspaceLifecycleService.handlerFor` in [`packages/agent-core-v2/app/scopes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/app/scopes.ts) provides automatic resource cleanup absent in v1
- Feature extensions in v2 use isolated seams in `src/features/*` versus direct subclassing in v1
- Experimental flags migrate from centralized registry (v1) to domain-local declarations (v2)
- Kimi Code's production kap-server runs exclusively on v2's architecture

## Frequently Asked Questions

### Can I migrate from v1 to v2 incrementally?

Yes. The v2 handler API mirrors v1's public surface—both implement the same `run()` method signature. You can port agents gradually by replacing `new Agent()` instantiation with `workspaceService.handlerFor()` resolution while preserving calling code.

### Does v2 impose measurable performance overhead?

The DI container and scope resolution in [`packages/agent-core-v2/app/scopes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/app/scopes.ts) add initialization cost suited for long-running server processes. For short-lived CLI invocations, v1's direct instantiation remains more efficient.

### Which version powers the public Kimi Code service?

The production kap-server uses **agent-core-v2 exclusively**. The v1 engine remains available for lightweight client-side tooling and backward compatibility per [`packages/agent-core/AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/AGENTS.md).

### How do I choose between subclassing Agent (v1) and creating a feature (v2)?

Subclass `Agent` in `packages/agent-core/src/agent` when you need immediate behavioral override without server infrastructure. Build a feature in `packages/agent-core-v2/src/features/*` when your capability requires scoped services, cross-cutting concerns, or safe rollout through `IFlagService`.