loopkit

LoopKit

Make the agent loop a durable, typed, replayable, budgeted execution primitive — engineered, tested, and operated like any other production system.

"Temporal for agent loops" — not another LangChain port.

60-Second Example

package main

import (
	"context"
	"encoding/json"
	"fmt"

	loopkit "github.com/wolmi/loopkit"
	"github.com/wolmi/loopkit/adapters/store/sqlite"
	"github.com/wolmi/loopkit/core/action"
	"github.com/wolmi/loopkit/core/event"
	"github.com/wolmi/loopkit/core/loop"
	"github.com/wolmi/loopkit/core/loop/outcome"
	"github.com/wolmi/loopkit/runtime"
)

type State struct{ Done bool }
type Result struct{ Answer string }

func main() {
	store, _ := sqlite.Open("/tmp/demo.db")

	def := loop.Definition[State, Result]{
		Name:      "demo",
		InitState: func() State { return State{} },
		Transition: func(_ loop.Context, s State, ev event.Envelope) (State, []action.Action, error) {
			switch ev.Kind {
			case event.KindIterationStarted:
				if !s.Done {
					args, _ := json.Marshal(map[string]string{"query": "hello"})
					return s, []action.Action{action.ToolCall{Tool: "echo", Args: args}}, nil
				}
			case event.KindToolCalled:
				res, _ := json.Marshal(Result{Answer: "42"})
				return State{Done: true}, []action.Action{action.Finish{Result: res}}, nil
			}
			return s, nil, nil
		},
	}

	runner := loopkit.New(def,
		loopkit.WithStore(store),
		loopkit.WithTools(echoTools{}),
		loopkit.WithMaxIterations(5),
	)

	o, _ := runner.Start(context.Background(), nil)
	outcome.Match(o,
		func(c outcome.Completed[Result]) string {
			fmt.Println("Answer:", c.Result.Answer)
			return ""
		},
		func(outcome.BudgetExceeded[Result]) string { fmt.Println("over budget"); return "" },
		func(outcome.Stuck[Result]) string { fmt.Println("stuck"); return "" },
		func(outcome.Interrupted[Result]) string { fmt.Println("interrupted"); return "" },
		func(outcome.PolicyDenied[Result]) string { fmt.Println("policy denied"); return "" },
		func(e outcome.Failed[Result]) string { fmt.Println("failed:", e.Err); return "" },
	)
}

type echoTools struct{}

func (echoTools) Describe() []runtime.ToolDescriptor {
	return []runtime.ToolDescriptor{{Name: "echo", Description: "Echo the query back"}}
}
func (echoTools) Execute(_ context.Context, req runtime.ToolRequest) (runtime.ToolResult, error) {
	return runtime.ToolResult{Result: req.Args}, nil
}

Install:

go get github.com/wolmi/loopkit@latest

Why LoopKit

Agent frameworks tell you how to write the loop. LoopKit tells you how to run it — crash-safely, on budget, with full replay and regression testing.

Architecture

┌────────────────────────────────────────────────────────────────┐
│  L5  TOOLING                                                   │
│      loopctl CLI · Trajectory Inspector UI · CI eval-gate      │
├────────────────────────────────────────────────────────────────┤
│  L4  QUALITY ENGINE                                            │
│      .loopfix fixtures · looptest.Replay · Eval harness        │
├────────────────────────────────────────────────────────────────┤
│  L3  GOVERNANCE                                                │
│      Budget (tokens/$/time/iter) · Policy · Convergence guard  │
├────────────────────────────────────────────────────────────────┤
│  L2  PROVIDERS & TOOLS                                         │
│      openaicompat · anthropic · gemini · MCP · A2A · WASM      │
├────────────────────────────────────────────────────────────────┤
│  L1  KERNEL                                                    │
│      event-sourced loop · sealed outcomes · durability proto   │
└────────────────────────────────────────────────────────────────┘

Hexagonal rules: core/* imports stdlib only. Adapters import core/runtime; never the reverse. OTel confined to adapters/telemetry/otel. Enforced by arch_test.go.

Feature Matrix

Legend: ✅ native · 🟡 partial · ❌ absent

Quickstart

1. Install

go get github.com/wolmi/loopkit@latest

2. Run the research-agent demo

# Interrupt + resume demo (flagship)
go run ./examples/research-agent/

# Full kill/resume walkthrough
bash examples/research-agent/demo.sh

3. Record and replay a run

# Build loopctl
go build -o loopctl ./cmd/loopctl/

# Record a loop run from a SQLite store
./loopctl record <loop-id> --store sqlite://path.db -o run.loopfix

# Strict replay (verifies chain hash)
./loopctl replay run.loopfix --strict

# Diff two trajectories
./loopctl diff run_a.loopfix run_b.loopfix --json

4. Test your loop

// In your _test.go:
func TestMyLoop(t *testing.T) {
    looptest.Replay(t, "testdata/my_run.loopfix",
        looptest.ExpectCompleted[MyResult](),
    )
}

Providers

Tools

Stores

Documentation

• Getting Started
• Concepts
• Budgets & Policy
• Testing Loops
• FAQ
• Contributing

License

Apache 2.0 — see LICENSE.