sp4rk

sp4rk - это Golang SDK для создания мультиагентных ИИ-систем. Он объединяет привычные агентные механизмы - цикл ReAct, вызов инструментов, маршрутизацию между несколькими LLM-провайдерами, серверы инструментов MCP, память сессий и оркестрацию Plan & Execute - за двумя точками входа: классическим API на основе Config для полного низкоуровневого контроля и текучим builder'ом для сборки агента цепочкой вызовов. Оба варианта возвращают одни и те же базовые типы, поэтому свободный (fluent) и классический код легко сочетаются. Проект находится на стадии ранней альфы, и в его README есть предупреждение, что API может меняться без предварительного уведомления.

Как устроен

SDK организован в четыре уровня, где импорты идут строго сверху вниз. Корневой пакет sp4rk содержит Framework, который владеет общей инфраструктурой - LLM-маршрутизатором, реестром инструментов, MCP-шлюзом и кэшем результатов работы инструментов, - а также выдаёт оркестраторы для отдельных сессий. Под ним находится уровень orchestration, координирующий многошаговые задачи. Ещё ниже расположен уровень agent, исполняющий одиночный цикл ReAct. В самом низу находятся примитивы: маршрутизатор и провайдеры llm, а также реестр tools со встроенными инструментами и MCP-прокси.

Многошаговая работа выполняется по схеме Plan & Execute. Компонент Planner превращает задачу в виде свободного текста в DAG шагов - либо напрямую (в один вызов LLM), либо через режим "informed", который сначала запускает короткий цикл исследования только для чтения, чтобы собрать контекст перед планированием. Conductor исполняет этот DAG по одному готовому шагу за раз, отслеживая общее состояние на доске Blackboard, передающей факты между шагами. Когда шаг завершается ошибкой, Reflector анализирует траекторию рассуждений, действий и наблюдений, возвращает анализ первопричины с предложением по исправлению, после чего Conductor повторяет попытку. Состояние исполнения можно сохранять в контрольных точках, чтобы задача переживала перезапуск.

Инструменты берутся из двух источников: встроенные для работы с файлами, шеллом и поиском, а также внешние серверы MCP. Шлюз MCP подключается к каждому настроенному серверу при запуске (через stdio или HTTP), обнаруживает его инструменты с помощью tools/list и регистрирует их в общем реестре - после этого для исполнителя инструмент MCP ничем не отличается от встроенного. Слой llm маршрутизирует каждый вызов активному провайдеру через Router, который безопасен для конкурентного использования, поддерживает переключение моделей во время работы и повторяет попытки при временных ошибках с нарастающей задержкой (backoff). Провайдеры поддерживают Anthropic и любые OpenAI-совместимые эндпоинты (OpenAI Chat Completions, Responses API, LM Studio, vLLM, прокси). Память сессий представляет собой управляемое контекстное окно с подключаемыми стратегиями сжатия (скользящее окно, суммаризация, иерархическое сжатие) и выборочной очисткой вывода инструментов, чтобы длинные диалоги не разрастались бесконечно.

Транспорт провайдера LLM работает по синхронной схеме запрос/ответ: метод Call у провайдера возвращает полный *ChatResponse, а не поток токенов. Наблюдаемость (observability) обеспечивается интерфейсом Events: исполнитель отправляет события жизненного цикла (начало шага, мысль, вызов инструмента, результат инструмента, заполнение контекста, сжатие), а также хуки AssistantChunk / AssistantDone для вывода в режиме печатной машинки. Достаточно встроить NoopEvents и переопределить только нужные методы.

Использование

Текучий builder входит в корневой пакет, поэтому отдельный импорт не нужен. Он возвращает тот же *sp4rk.Framework, что создаётся классическим конструктором sp4rk.New, а инструмент завершения регистрируется автоматически, позволяя агенту сигнализировать об окончании работы:

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)
}

В репозитории есть одиннадцать готовых к запуску примеров в директории examples/: от минимального агента до собственных инструментов, потоковой передачи событий, подтверждений от человека (human-in-the-loop), интеграции с MCP, схемы plan-and-reflect, мультипровайдерной маршрутизации, параллельных субагентов, контекстной памяти и полноценной комбинации всех возможностей.

Ограничения

Проект находится на стадии ранней альфы, разрабатывается одним автором и ещё не имеет релизов: в самом README написано, что не стоит полагаться на него в продакшене или критичных сценариях, а возможности и внутренние API могут меняться без предупреждения. У него нет тегированных релизов и на момент написания нет звёзд, issue или форков. Набор провайдеров ограничен Anthropic и OpenAI-совместимыми эндпоинтами. Вызовы LLM синхронны на уровне транспорта (запрос/ответ); если требуется настоящая потоковая передача токенов напрямую из сокета провайдера, стоит проверить текущую реализацию провайдера, прежде чем полагаться на хук AssistantChunk. Из-за своего состояния sp4rk находится в watchlist в ожидании первого релиза и признаков использования кем-то, кроме автора.

Связанные инструменты для агентов на Golang в этой базе: adk-go (порт Google Agent Development Kit), go-step-sequences (пошаговые агентные потоки), botctl и flue.

Репозиторий: https://github.com/v0lka/sp4rk - 0 звёзд, лицензия MIT.