sp4rk Agent SDK

Warning

Early Alpha Stage — This project is under active development and not yet stable. Features, APIs, and internal parts may change without notice. Use at your own risk. Do not rely on it for production or critical workflows.

A standalone Go SDK for building AI agent systems with Plan & Execute orchestration, tool integration, and multi-provider LLM support. Long-running runs can be paused and resumed, steered with live user messages at step boundaries, and configured to run a trusted verifier after file edits. Tool capability groups provide fail-closed selection and policy boundaries, while purpose-aware sampling separates creative executor calls from deterministic routing, compaction, and summarization calls.

Quick start

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/v0lka/sp4rk"
)

func main() {
	// sp4rk.NewF is the fluent entry point; it returns a real *sp4rk.Framework
	// (the same type the classic sp4rk.New constructor returns). The finish tool
	// is auto-registered so the agent can signal completion.
	fw, err := sp4rk.NewF().
		Anthropic(os.Getenv("ANTHROPIC_API_KEY"), "claude-sonnet-4-5").
		Build()
	if err != nil {
		panic(err)
	}
	defer fw.Shutdown()

	// Run a single ReAct loop and return the original *orchestration.ExecutionResult.
	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 fluent builders are part of the root sp4rk package (no separate import): they return the original SDK types (*sp4rk.Framework, *orchestration.ExecutionResult) and delegate every call to the underlying API, so you can mix fluent and classic code freely. For the classic sp4rk.Config API (full low-level control), see Getting started.

New here? Read the Fluent API guide for the layer map, before/after comparisons, and when to reach for classic escapes.

Documentation

Detailed guides live in docs/:

• Getting started — installation, configuration, first run
• Architecture — layered design and package layout
• Agent executor — the execution loop, cooperative pause/live steering, and verify-on-edit
• Orchestration — Plan & Execute mode, resumable checkpoints, and interjections
• Planner — plan generation
• Reflector — self-reflection
• LLM providers — Anthropic, OpenAI (Chat Completions + Responses), Google (Gemini/Gemma), OpenAI-compatible endpoints, purpose-aware sampling, multi-protocol routing, and multimodal content blocks
• Tools — built-in tools, capability groups, and the registry
• Tool safety — advisory/strict judging, escalation severity, and execution-context safety
• MCP integration — Model Context Protocol gateway
• Memory — compaction and persistence
• Embedding & vector search — semantic search
• Security — tool policies and safety
• Skills — reusable skill packages
• Subagent Profiles — AGENT.md-declared subagent personas and tool budgets
• Subagents — delegated execution
• Human-in-the-loop — confirmations and ask-user
• Events — streaming event types
• Prompt building — system prompt assembly
• Utilities — path, string, process, and ignore helpers

Runnable examples are in examples/.

License

MIT