KODE SDK Documentation

KODE SDK is an Agent Runtime Kernel designed to manage the complete lifecycle of AI agents. It acts as a runtime layer (similar to how V8 manages JavaScript) that provides:

• Agent lifecycle management: Create, run, pause, resume, and fork agents.
• State persistence: Crash recovery using Write-Ahead Logging (WAL) protection.
• Tool execution: Managed execution with permission governance.
• Observability: A three-channel event system for monitoring and control.

Note: KODE SDK does not handle HTTP routing, user authentication, multi-tenancy, or horizontal scaling; these must be architected in your application layer.

To track the lifecycle and execution progress of an agent, monitor AgentRuntimeState and BreakpointState.

AgentRuntimeState describes the high-level status:

• READY: Agent is idle.
• WORKING: Agent is processing a message.
• PAUSED: Agent is waiting for a permission decision.

BreakpointState provides granular execution steps:

• READY, PRE_MODEL, STREAMING_MODEL, TOOL_PENDING, AWAITING_APPROVAL, PRE_TOOL, TOOL_EXECUTING, POST_TOOL.

type AgentRuntimeState = 'READY' | 'WORKING' | 'PAUSED';

type BreakpointState =
  | 'READY'
  | 'PRE_MODEL'
  | 'STREAMING_MODEL'
  | 'TOOL_PENDING'
  | 'AWAITING_APPROVAL'
  | 'PRE_TOOL'
  | 'TOOL_EXECUTING'
  | 'POST_TOOL';

Choosing the right backend depends on your deployment scale and requirements.

When to Choose SQLite

• Use Case: Development, Single Instance, Quick prototyping.
• Scale: Less than 1000 Agents and less than 100K messages per day.
• Pros: Zero config, file-based, low maintenance.

When to Choose PostgreSQL

• Use Case: Production, Multi-Instance, High availability.
• Scale: More than 1000 Agents and more than 100K messages per day.
• Pros: Concurrent writes, complex JSONB queries, optimized for large datasets.

Agents can perform periodic tasks or send non-intrusive reminders using the built-in scheduler.

• Step-based Scheduling: Use agent.schedule().everySteps(N, callback) to trigger logic every N steps.
• System Reminders: Use agent.remind(text, options) to send reminders via the Monitor. These are separate from the Progress stream and do not clutter the main agent output.
• External Triggers: For high-frequency tasks or integration with external Cron jobs, use scheduler.notifyExternalTrigger to wake the agent.
• Todo Management: Use remindIntervalSteps in a Todo configuration to ensure periodic reviews of pending tasks.

Breaking changes should be avoided. If they are unavoidable, you must follow these requirements:

1. Mark the PR: Include BREAKING in the PR title or description.
2. Submit a Report: Provide a detailed report including:
   • Scope of impact
   • Migration steps
   • Transition strategy (e.g., compatibility layers, deprecation periods)
   • Risks
   • Rollback plan
3. Provide Solutions: Always attempt to provide transition solutions for users.

KODE SDK categorizes errors into five types to help the model and the system decide how to react. Understanding these is critical for implementing smart retry logic or UI notifications.

For workloads between 100 and 1000 concurrent agents, implement Agent Sharding. This strategy involves using consistent hashing on the agentId to route specific agents to specific worker processes.

Routing Logic Example: hash(agentId) % N = worker_index (where N is the number of workers).

Every skill requires a SKILL.md file in its directory. This file uses YAML frontmatter for metadata and Markdown for content. The name in the YAML must match the directory name.

Required Fields:

• name: Skill identifier (must match folder name).
• description: Description used for automatic injection into the Agent's system prompt.

Directory Structure:

.skills/
├── skill-name/
│   ├── SKILL.md            # Required definition
│   ├── references/         # Reference documents
│   ├── scripts/            # Executable scripts
│   └── assets/             # Static resources
└── .archived/
    └── archived-skill/

---
name: skill-name
description: Skill description
---

# Skill Name

Brief description of the skill's functionality.

## Use Cases

- Case 1
- Case 2

## Usage Guide

Detailed instructions for using this skill...

When building with KODE SDK, keep the following runtime characteristics in mind:

Memory Footprint

A typical agent instance consumes between 100KB and 5MB, depending on message history and media cache. An AgentPool of 50 agents may require 5MB to 250MB of memory.

I/O and Scaling

• I/O Overhead: Each agent step incurs approximately 30-70ms of I/O overhead (persistence and event emission).
• Concurrency: For high-concurrency environments (e.g., 100+ agents), avoid JSONStore due to sequential bottlenecks. Instead, use SqliteStore or PostgresStore to support parallel writes.
• Event Loop: While most heavy operations are async, be cautious with synchronous operations in custom tools, as they can block the event loop.

In current versions (v2.7.0), the SDK uses JSONStore for file persistence. To support database persistence, you can implement the Store interface.

Planned improvements in v2.8 will introduce appendMessage() for incremental updates and loadMessagesPaginated() for handling large histories. When implementing a custom store, ensure it satisfies the core Store interface requirements to allow for seamless integration with the Agent lifecycle.

interface Store {
  // Existing methods...

  // NEW (v2.8): Incremental append (optional, for performance)
  appendMessage?(agentId: string, message: Message): Promise<void>;

  // NEW (v2.8): Paginated loading (optional, for large histories)
  loadMessagesPaginated?(agentId: string, opts: {
    offset: number;
    limit: number;
  }): Promise<Message[]>;
}