# 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:

```go
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 [[toolbox/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 [[toolbox/flue]].

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