mark3labs/kit/kit-sdk

Kit SDK Development Guide

The Kit SDK (pkg/kit) lets you embed Kit's full agent capabilities — LLM interactions, tool execution, session management, streaming, hooks — into any Go application. Unlike extensions (which are interpreted scripts running inside Kit's TUI), SDK programs are standalone compiled Go binaries.

This file is the entry point. It gives the installation, a quick start, the core lifecycle, and the rules you must never miss. Detailed material lives in the references/ directory (see Reference files below). Read only the reference files that apply to your task.

Installation

go get github.com/mark3labs/kit

Import path (alias recommended):

import kit "github.com/mark3labs/kit/pkg/kit"

Quick Start

package main
 
import (
    "context"
    "fmt"
    "log"
 
    kit "github.com/mark3labs/kit/pkg/kit"
)
 
func main() {
    ctx := context.Background()
 
    host, err := kit.New(ctx, nil) // nil = normal config-file discovery and field resolution
    if err != nil {
        log.Fatal(err)
    }
    defer func() { _ = host.Close() }()
 
    response, err := host.Prompt(ctx, "What is 2+2?")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(response)
}

Core Lifecycle

1. Create: kit.New(ctx, opts) — loads config, initializes MCP servers, creates LLM provider, sets up agent
2. Interact: host.Prompt(ctx, msg) — send messages, agent uses tools as needed
3. Close: host.Close() — cleans up MCP connections, model resources, session file handle

Always defer Close():

defer func() { _ = host.Close() }()

API Map

A minimal custom tool, which is the most common extension point:

type WeatherInput struct {
    City string `json:"city" description:"City name, e.g. 'San Francisco'"`
}
 
weatherTool := kit.NewTool("get_weather", "Get current weather for a city",
    func(ctx context.Context, input WeatherInput) (kit.ToolOutput, error) {
        return kit.TextResult("72°F, sunny in " + input.City), nil
    },
)
 
host, _ := kit.New(ctx, &kit.Options{
    ExtraTools: []kit.Tool{weatherTool},
})

Critical Rules (never skip)

1. `Tools` replaces, `ExtraTools` adds. Options.Tools replaces default core tools, not MCP or extension tools. Options.ExtraTools adds tools alongside the defaults. Use Tools to replace core tools; use ExtraTools to extend them.
2. Register events and hooks before calling `Prompt`. Subscribers and hooks return an unsubscribe function — defer unsub() if the handler must not outlive a scope.
3. Events are read-only; hooks are read-write. Use host.On<Event> to observe. Use host.On<Hook>(priority, fn) to block, modify, or inject. In hooks, return nil to allow/pass through; the first non-nil result wins. Lower priority values run first (kit.HookPriorityHigh = 0, Normal = 50, Low = 100).
4. Pointer fields mean "unset". Generation parameters like Temperature, TopP, TopK are pointers so an explicit 0.0 differs from "leave the provider default". Zero-value MaxTokens auto-resolves; a non-zero value suppresses right-sizing.
5. Sessions persist automatically as JSONL tree files. No explicit save call exists or is needed. Use NoSession: true for ephemeral, in-memory agents (scripts, subagents, tests).
6. Context-window fill is not `InputTokens` alone. With prompt caching, sum InputTokens + CacheReadTokens + CacheCreationTokens + OutputTokens from result.FinalUsage.
7. Reactive compaction is always on. A context-overflow error triggers one compact-and-replay. AutoCompact: true adds proactive compaction before turns that near the limit. If the replay still overflows, the turn fails with kit.ErrContextOverflow.
8. MCP OAuth is opt-in. If MCPAuthHandler is nil, remote MCP servers that require OAuth fail with an authorization-required error. They do not open a browser silently.
9. No dependency-name leakage. Use the kit.LLM* type aliases (LLMMessage, LLMUsage, ...) and kit.ConvertToLLM* helpers. Do not import the underlying LLM library into SDK-facing code.
10. Configuration file selection is not field precedence. An explicit ConfigFile selects only that file; otherwise project config is preferred to home config. Effective generation/provider fields use explicit SDK values → environment → configuration → per-model/fallback values. Stored credentials beat provider environment variables unless explicitly overridden. See references/configuration.md. kit.New handles setup; use kit.InitConfig only for special cases.

Reference files

Read the file that matches the task. Paths are relative to this skill's root directory.

Key Files for Reference

• `pkg/kit/kit.go` — Kit struct, New(), Prompt methods, Subagent, Close
• `pkg/kit/extension_api.go` — ExtensionAPI interface, kit.Extensions() accessor
• `pkg/kit/types.go` — Re-exported types from internal packages
• `pkg/kit/tools.go` — Tool constructors and bundles
• `pkg/kit/events.go` — Event types, EventBus, typed subscribers
• `pkg/kit/hooks.go` — Hook system (BeforeToolCall, AfterToolResult, etc.)
• `pkg/kit/sessions.go` — Session management
• `pkg/kit/compaction.go` — Context compaction
• `pkg/kit/models.go` — Model registry lookups
• `pkg/kit/config.go` — Config initialization and defaults
• `pkg/kit/skills.go` — Skills loading and prompt building
• `pkg/kit/auth.go` — Credential management
• `examples/sdk/` — Working example programs