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

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, 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, accessed through:

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.

Code Examples: Architecture in Practice

Creating a Standalone Agent (v1)

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)

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 implementation ensures the handler runs within proper cleanup boundaries.

Registering a Feature Flag (v2)

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, 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 — v1 design rules and constraints
• packages/agent-core/src/agent/* — Agent class implementation
• packages/agent-core-v2/AGENTS.md — v2 scoped architecture overview
• 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 — 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 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 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}