🚀 AgentKernel

A lightweight, embeddable, WebSocket-driven AI Runtime Kernel

💡 An ultra-lightweight Agent kernel that makes integrating AI into your projects a breeze! Zero-embedding, high concurrency—using it is as simple as using an object. Everything communicates via the WebSocket protocol, requiring no tight coupling to your project code. A completely independent microservice!

🌐 Online Demo: https://cih1996.github.io/AgentKernel/
📺 Video Tutorial (How to integrate):

Tool capabilities, Skills, and MCP can be freely and dynamically hot-plugged, registered, and invoked via callbacks.

Various event callbacks are pre-packaged, saving you from reinventing the wheel:

1. Context Management: Context activation, truncation, injection, threshold detection, and full-history queries.
2. Multi-Model Compatibility: Compatible with providers like OpenAI, Claude, and Ollama.
3. Dynamic Tool Dispatch: Real-time registration of capability tools, executed by you via callbacks, including MCP.

You can even build the next Open Code, Claude Code, OpenClaw, etc.! Because it serves as the core communication base for AI, you no longer need to worry about provider compatibility, TOOL protocols, or context management. Everything is encapsulated, yet remains fully dynamic and customizable in real-time!

AgentKernel is neither a Chat UI nor a Business Agent, but an Agent Runtime Kernel.

Core Principle: AgentKernel handles the AI runtime; your project owns its product logic.

💡 Integration Note AgentKernel is better suited as an independently running AI kernel: your project connects to it after startup and uses different sessions as needed.
For multi-user shared sessions or collaborative viewing, it is recommended that your project handles distribution, broadcasting, and permission control at the upper layer, rather than having multiple client endpoints directly connect to the same session in the Core.
The Core is responsible for the runtime and protocol boundaries, not multi-user collaborative orchestration.

flowchart LR
    K[Start AgentKernel\nlistens on ws://localhost:9991/ws]
    P[Your Project\nWebsite / App / Backend]
    U[User]

    P -->|Connect to the Kernel port| K
    U -->|Send a message| P
    P -->|Forward message to Kernel| K
    P -->|Register capabilities\ne.g. database / messaging / device actions| K
    K -->|When AI needs a capability\ncall back your project| P
    P -->|Execute capability\nand return result| K
    K -->|Return AI response and progress| P
    P -->|Display to user| U

• Start AgentKernel first. It listens on a WebSocket port.
• Your project connects to this port, then sends messages, registers capabilities, and receives AI progress events.
• When AI needs a capability, AgentKernel calls back your project. Your project executes it and returns the result, then the Kernel continues inference.
• Your project can reuse the same connection for multiple sessions.

AgentKernel uses WebSocket as its core bidirectional communication protocol. In plain words: your project sends messages to the Kernel, the Kernel talks to the model, and if the model needs a capability, the Kernel calls your project back to execute it.

sequenceDiagram
    participant U as User
    participant P as Your Project
    participant K as AgentKernel Kernel
    participant M as AI Model

    P->>K: Connect to Kernel port after startup
    P->>K: Register capabilities, such as search, messaging, or file actions
    U->>P: Ask a question
    P->>K: Send the user's message to the Kernel
    K->>M: Ask AI to generate a response
    M-->>K: Return text, streamed back as it arrives
    K-->>P: Keep sending AI progress and output

    alt AI needs a capability
        K-->>P: Ask your project to execute a capability
        P->>P: Your project executes it
        P->>K: Return execution result to Kernel
        K->>M: Continue AI generation with the result
        M-->>K: Continue generating
        K-->>P: Return final response
    else AI does not need a capability
        K-->>P: Return final response directly
    end

    P-->>U: Show the AI response

In this flow, AgentKernel does not care how your business works and does not force your project to use a specific language. Your project only needs to connect via WebSocket, send messages, register capabilities, and handle callbacks.

1. 🔌 Dynamic Hot-Pluggable Tool Capabilities: No need to modify Kernel source code. The business side dynamically registers tool definitions via WS, receives tool.call.request, executes locally, and returns the result.
2. 📚 Full History and Controllable Views: Message Logs are permanently retained, but an Active Context View is provided. The Kernel only exposes threshold events and does not hardcode compression strategies, leaving it to the business side's discretion.
3. ⚡ Event Streams as First-Class Citizens: Proactively pushes states like model.delta and tool.call.request during execution. If the provider supports reasoning/thinking stream passthrough, it also outputs via model.delta.payload.event_type = "thinking", facilitating debugging and distributed deployment.
4. 🪶 Extremely Lightweight: Does not have built-in heavy memory systems, rule libraries, or skill markets. Sticks to its boundaries, acting purely as a cross-platform reusable Runtime.

These projects work well with AgentKernel and can quickly add MCP discovery, execution, and local system-operation capabilities:

• agentkernel-mcp-framework: An independent MCP discovery and execution tool, suitable as the bridge between your project and MCP capabilities.
• agentkernel-capabilities: A basic system-operation MCP that provides common capabilities such as search, file lookup, file reading, file editing, and Bash execution.

First, start the Core:

git clone https://github.com/cih1996/AgentKernel.git
cd AgentKernel
cargo run

• cargo run starts the headless Core service.
• Default WebSocket address: ws://localhost:9991/ws
• If your default binary is not the server, you can explicitly use cargo run -p agentkernel-server

If you need a local web debugging console, start it separately:

cd web
python3 server.py

• Default debug page address: http://127.0.0.1:8899
• web/server.py will first check if the Core is running; if not, it will prompt and exit directly.
• The recommended sequence is to start the Core first, then the debug page.

💡 For official business integration, it is recommended to keep your Python / Node.js / Go / Rust service persistently connected to the Core, and reuse the connection with different session_ids. If a user needs to "stop generating", the business service should send run.cancel. Do not let multiple end clients directly compete for the same shared session.

.aicore/
└── sessions/
    └── <session_id>/
        ├── session.json
        ├── messages.jsonl
        ├── events.jsonl
        └── ...

{
  "command": "session.send",
  "session_id": "debug",
  "payload": { "message": "Get current time" }
}

{
  "command": "tool.register",
  "session_id": "debug",
  "payload": { "tool_name": "get_time", "schema": { "type": "object" } }
}

// Kernel -> Client (Event)
{
  "type": "event",
  "event_type": "tool.call.request",
  "payload": { "tool_name": "get_time", "call_id": "xxx" }
}

// Client -> Kernel (Command)
{
  "command": "tool.execute.result",
  "payload": { "call_id": "xxx", "result": "2026-05-18 08:30:00" }
}

Runtime Console	Session Management	Tool Runtime
Event Stream	Raw Messages	Config and Prompt

• Complete Context operations and Compaction workflow
• Tool call ACK / Idempotent state queries
• SQLite main storage and multi-client permission boundaries
• SDK Examples (JS / Python / Go)

License: MIT
Friendly Links: LINUX DO
Community Chat: