sp4rk

sp4rk is a Golang SDK for building multi-agent AI systems. It wraps the usual agent machinery — a ReAct loop, tool calling, multi-provider LLM routing, MCP tool servers, session memory, and Plan & Execute orchestration — behind two entry points: a classic Config-driven API for full low-level control, and a fluent builder for assembling an agent in a few chained calls. Both return the same underlying types, so fluent and classic code mix freely. The project is in early alpha and its README warns that APIs may change without notice.

How it works

The SDK is organized in four layers, with imports flowing strictly downward. The root sp4rk package holds the Framework, which owns the shared infrastructure — the LLM router, the tool registry, the MCP gateway, and the tool-result cache — and hands out per-session orchestrators. Below it, the orchestration layer coordinates multi-step tasks. Below that, the agent layer runs a single ReAct loop. At the bottom sit the primitives: the llm router and providers, and the tools registry with its built-ins and MCP proxy.

Multi-step work runs as Plan & Execute. A Planner turns a free-text task into a DAG of steps — either directly (one LLM call) or through an "informed" mode that first runs a short read-only exploration loop to gather context before planning. The Conductor executes that DAG one ready step at a time, tracking shared state in a Blackboard that carries facts forward between steps. When a step fails, a Reflector analyzes the trajectory of thoughts, actions, and observations, returns a root-cause analysis and a suggested recovery action, and the Conductor retries. Execution state can be checkpointed so a task survives a restart.

Tools come from two places: built-ins for file, shell, and search operations, and external MCP servers. The MCP gateway connects to each configured server at startup (over stdio or HTTP), discovers its tools via tools/list, and registers them in the shared registry — from there an MCP tool is indistinguishable from a built-in to the executor. The llm layer routes each call to the active provider through a Router that is safe for concurrent use, supports runtime model switching, and retries transient errors with backoff. Providers cover Anthropic and any OpenAI-compatible endpoint (OpenAI Chat Completions, the Responses API, LM Studio, vLLM, proxies). Session memory is a managed context window with pluggable compaction strategies (sliding window, summarization, hierarchical) and selective tool-output pruning to keep long conversations from growing without bound.

The LLM provider transport is synchronous request/response — a provider's Call returns a complete *ChatResponse rather than a token stream. Observability instead comes through the Events interface: the executor emits lifecycle events (step start, thought, tool call, tool result, context fill, compaction) plus AssistantChunk / AssistantDone hooks for live-typing output. Embed NoopEvents and override only the methods you care about.

Usage

The fluent builder is part of the root package, so there is no separate import. It returns the same *sp4rk.Framework the classic sp4rk.New constructor produces, and the finish tool is auto-registered so the agent can signal completion:

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/v0lka/sp4rk"
)

func main() {
	fw, err := sp4rk.NewF().
		Anthropic(os.Getenv("ANTHROPIC_API_KEY"), "claude-sonnet-4-5").
		Build()
	if err != nil {
		panic(err)
	}
	defer fw.Shutdown()

	result, err := fw.RunF(context.Background()).
		System("You are a helpful assistant.").
		Ask("Write a hello world in Go")
	if err != nil {
		panic(err)
	}
	fmt.Println(result.Output)
}

The repo ships eleven runnable examples under examples/, from a minimal agent through custom tools, event streaming, human-in-the-loop confirmations, MCP integration, plan-and-reflect, multi-provider routing, parallel subagents, context memory, and a "full power" combination.

Limitations

The project is early alpha, single-author, and unreleased — the README's own warning says not to rely on it for production or critical workflows, and that features and internal APIs may change without notice. It has no tagged releases and, at the time of writing, no stars, issues, or forks. The provider set is limited to Anthropic and OpenAI-compatible endpoints. LLM calls are synchronous request/response at the transport level; if you need genuine token-by-token streaming from the provider socket, confirm the current provider implementation before relying on the AssistantChunk hook. Because of its stage, sp4rk is on the watchlist pending a first release and signs it is used beyond its author.

Related Golang agent tooling in this vault: adk-go (Google's Agent Development Kit port), go-step-sequences (step-based agent flows), botctl, and flue.

Repo: https://github.com/v0lka/sp4rk — 0 stars, MIT license.