agent

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 18, 2026 License: MIT Imports: 7 Imported by: 0

README

github.com/stelmakhdigital/stell-agent

Runtime-слой агента: цикл LLM+tools, сессии, инструменты и хуки.

Продуктовая оркестрация (Service, extensions, discovery) живёт в github.com/stelmakhdigital/stell-coding и либо управляет Agent там, либо вызывает Loop напрямую.

Возможности

  • Loop / Run / RunContinue — низкоуровневый ход LLM + tools
  • Agent — очереди steer/follow-up и подписка на события
  • ConvertToLlm / PrepareMessages — контекст сессии → сообщения LLM
  • JSONL session store с деревом веток и компактированием
  • Builtin tools runtime (read / bash / …)
  • In-process hook bus

Карта директорий

Путь Назначение
loop.go, agent.go, streamfn.go цикл хода, публичный Agent API, StreamFn
events.go, convert.go, toolexec.go события, конвертация, исполнение tools
session/ JSONL-сессии, дерево, branch, compact
tools/ runtime и builtin tools
hooks/ имена хуков и Bus
harness/ оценка контекста, compaction helpers
proxy/ HTTP SSE StreamProxy

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

import (
	"github.com/stelmakhdigital/stell-agent"
	"github.com/stelmakhdigital/stell-agent/session"
	"github.com/stelmakhdigital/stell-agent/tools"
	"github.com/stelmakhdigital/stell-ai/provider"
)

reg := provider.BuildRegistry()
rt := tools.NewRuntime()
tools.RegisterBuiltins(rt)
sess, _ := session.Open(...) // или session.NewManager

loop := &agent.Loop{Registry: reg, Tools: rt, Sessions: sess}
// ch, err := loop.Run(ctx, userMsg)
_ = loop

Documentation

Overview

Package agent — runtime-слой агента: цикл LLM+tools, сессии, хуки.

Роль в монорепо: `github.com/stelmakhdigital/stell-agent` стоит между `github.com/stelmakhdigital/stell-ai` и `github.com/stelmakhdigital/stell-coding`. Продуктовая оркестрация (Service, extensions, discovery) живёт в coding-agent; этот пакет даёт Loop / Agent, хранилище сессий и встроенные инструменты.

Основные импорты:

  • github.com/stelmakhdigital/stell-agent — Loop, Agent, события, ConvertToLlm
  • github.com/stelmakhdigital/stell-agent/session — JSONL-сессии и дерево веток
  • github.com/stelmakhdigital/stell-agent/tools — runtime встроенных инструментов
  • github.com/stelmakhdigital/stell-agent/hooks — in-process шина хуков
  • github.com/stelmakhdigital/stell-agent/harness — компактирование / helpers system prompt
  • github.com/stelmakhdigital/stell-agent/proxy — StreamFn через HTTP SSE

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ConvertMessagesDefault 

func ConvertMessagesDefault(msgs []ai.Message) []ai.Message

ConvertToLlm доступен для embedders.

func ConvertToLlm 

func ConvertToLlm(messages []ai.Message) []ai.Message

ConvertToLlm фильтрует сообщения сессии до ролей, понятных LLM, перед вызовом провайдера.

func PrepareMessages 

func PrepareMessages(messages []ai.Message, transform TransformContext) []ai.Message

PrepareMessages выполняет transform (если задан), затем ConvertToLlm.

func ShouldTerminateToolBatch 

func ShouldTerminateToolBatch(outcomes []ToolCallOutcome) bool

ShouldTerminateToolBatch возвращает true, если batch не пуст и у всех outcome установлен Terminate.

Types

type AfterAssistantTurn 

type AfterAssistantTurn func(ctx context.Context, iter int, turn AssistantTurn) (action TurnDecision, doneStopReason string, skipDoneEmit bool, err error)

AfterAssistantTurn определяет поведение после записи assistant-сообщения. Если nil, Loop останавливается без tool calls, иначе выполняет их. skipDoneEmit: при Action TurnDone Loop не отправляет EventDone (вызывающий уже отправил).

type AfterTools 

type AfterTools func(ctx context.Context, iter int, outcomes []ToolCallOutcome) (continueLoop bool, err error)

AfterTools выполняется после batch инструментов (saveSession, tool-error steer). continueLoop=false завершает цикл без max_iterations (вызывающий отправил done).

type Agent 

type Agent struct {
	Loop Loop

	SteeringMode QueueMode
	FollowUpMode QueueMode
	// contains filtered or unexported fields
}

Agent — публичный API: очереди + subscribe + Loop.

func NewAgent 

func NewAgent(reg *provider.Registry, rt *tools.Runtime, sess *session.Manager, modelName, modelID string) *Agent

NewAgent создаёт Agent, привязанный к registry, tools и session.

func (*Agent) FollowUp 

func (a *Agent) FollowUp(message string)

FollowUp ставит follow-up в очередь после завершения текущего хода.

func (*Agent) Prompt 

func (a *Agent) Prompt(ctx context.Context, message string, events chan<- Event)

Prompt запускает цикл агента для сообщения пользователя и рассылает события подписчикам и в опциональный канал events (не закрывается, если nil).

func (*Agent) Steer 

func (a *Agent) Steer(message string)

Steer ставит steering-сообщение в очередь для активного хода.

func (*Agent) Subscribe 

func (a *Agent) Subscribe(buf int) (<-chan Event, func())

Subscribe возвращает канал событий агента. Для остановки вызовите unsubscribe.

type AssistantTurn 

type AssistantTurn struct {
	Message    ai.Message
	ToolCalls  []ai.ToolCall
	StopReason string
	Usage      *ai.Usage
	// SkipAppend — ProcessStream уже сохранил assistant-сообщение.
	SkipAppend bool
}

AssistantTurn — результат прокачки одного потока модели в сессию и события.

type AutoRetryInfo 

type AutoRetryInfo struct {
	Attempt      int
	MaxAttempts  int
	DelayMs      int
	ErrorMessage string
	WillRetry    bool
	Success      bool
	FinalError   string
}

AutoRetryInfo описывает автоматический цикл повтора провайдера.

type Event 

type Event struct {
	Type          EventType
	Token         string
	Thinking      string
	Message       ai.Message
	MessageUpdate *MessageUpdate
	AutoRetry     *AutoRetryInfo
	ToolCall      *ai.ToolCall
	ToolCallDelta string
	ToolCallIndex int
	ToolCallID    string
	ToolCallName  string
	ToolResult    *ToolResult
	Usage         *ai.Usage
	StopReason    string
	WillRetry     bool
	Notice        string
	Err           error
}

Event генерируется циклом агента для подписчиков UI, RPC и SDK.

type EventType 

type EventType string

EventType — события цикла агента. 

const (
	EventToken          EventType = "token"
	EventThinkingToken  EventType = "thinking"
	EventMessageStart   EventType = "messageStart"
	EventMessage        EventType = "message"
	EventMessageUpdate  EventType = "messageUpdate"
	EventToolCall       EventType = "toolCall"
	EventToolCallDelta  EventType = "toolCallDelta"
	EventToolProgress   EventType = "toolProgress"
	EventToolResult     EventType = "toolResult"
	EventDone           EventType = "done"
	EventError          EventType = "error"
	EventAutoRetryStart EventType = "autoRetryStart"
	EventAutoRetryEnd   EventType = "autoRetryEnd"
	EventNotice         EventType = "notice"
	EventLabel          EventType = "label"
)

type FollowUpMessage 

type FollowUpMessage func() (msg ai.Message, ok bool)

FollowUpMessage извлекает in-loop follow-up из очереди.

type Loop 

type Loop struct {
	Registry  *provider.Registry
	Tools     *tools.Runtime
	Sessions  *session.Manager
	ModelName string
	ModelID   string

	BuildSystem      func(ctx context.Context) string
	ConvertMessages  func(messages []ai.Message) []ai.Message
	TransformContext func(ctx context.Context, messages []ai.Message) []ai.Message
	MaxIterations    int
	SteerFn          func() (message string, ok bool)
	SteerMessage     SteerMessage
	ToolExecution    ToolExecutionMode

	BeforeToolCall func(ctx context.Context, call ai.ToolCall) (block bool, args map[string]any)
	AfterToolCall  func(ctx context.Context, call ai.ToolCall, outcome ToolCallOutcome) ToolCallOutcome
	PrepareChat    func(ctx context.Context, iter int, base ai.ChatRequest) ai.ChatRequest
	OnToolProgress func(call ai.ToolCall, partial string)

	StreamFn            StreamFn
	ProcessStream       ProcessStreamFn
	PrepareNextTurn     PrepareNextTurn
	AfterAssistantTurn  AfterAssistantTurn
	ShouldStopAfterTurn ShouldStopAfterTurn
	FollowUpMessage     FollowUpMessage
	AfterTools          AfterTools
	AfterChatError      func(ctx context.Context, err error) (retry bool, notice string)

	// SkipUserAppend — вызывающий уже добавил user-сообщение.
	SkipUserAppend bool

	// SuppressMaxIterationsDone подавляет EventDone при достижении лимита итераций,
	// чтобы вызывающий мог выполнить финальный ход (продуктовый путь).
	SuppressMaxIterationsDone bool

	// LastStopReason устанавливается при выходе из цикла (для продуктового postamble).
	LastStopReason string
	// contains filtered or unexported fields
}

Loop — низкоуровневый исполнитель хода агента. Оркестрация продукта (расширения, discovery, сохранение настроек) остаётся в coding-agent и заполняет эти поля перед вызовом Run.

func (*Loop) ContinuePrepared 

func (l *Loop) ContinuePrepared(ctx context.Context, ch chan<- Event) error

ContinuePrepared — как RunContinue, но не закрывает ch.

func (*Loop) Run 

func (l *Loop) Run(ctx context.Context, prompt string, ch chan<- Event)

Run выполняет один user-prompt через LLM и инструменты, пока модель не перестанет вызывать инструменты или не будет достигнут MaxIterations. События отправляются в ch; ch закрывается при возврате Run.

func (*Loop) RunContinue 

func (l *Loop) RunContinue(ctx context.Context, ch chan<- Event)

RunContinue продолжает цикл без нового user-сообщения. Последнее сообщение сессии не должно быть assistant, ожидающим инструменты — обычно это tool result.

func (*Loop) RunPrepared 

func (l *Loop) RunPrepared(ctx context.Context, prompt string, ch chan<- Event)

RunPrepared — как Run, но не закрывает ch (канал принадлежит вызывающему).

type MessageUpdate 

type MessageUpdate struct {
	EventType    string
	ContentIndex int
	Delta        string
	Partial      ai.Message
	ToolCall     *ai.ToolCall
}

MessageUpdate — патч streaming assistant-сообщения.

type PrepareNextTurn 

type PrepareNextTurn func(ctx context.Context, iter int) error

PrepareNextTurn выполняется в начале каждой итерации (wrap-up steers, notices).

type ProcessStreamFn 

type ProcessStreamFn func(ctx context.Context, stream <-chan ai.ChatEvent, ch chan<- Event) (AssistantTurn, error)

ProcessStreamFn потребляет поток провайдера и генерирует продуктовые события. Если nil, Loop использует стандартный pump token/toolCall и AppendMessage.

type QueueMode 

type QueueMode string

QueueMode — режим очереди steer/follow-up. 

const (
	QueueOneAtATime QueueMode = "one-at-a-time"
	QueueAll        QueueMode = "all"
)

type ShouldStopAfterTurn 

type ShouldStopAfterTurn func(ctx context.Context, iter int, turn AssistantTurn, outcomes []ToolCallOutcome) (stop bool, err error)

ShouldStopAfterTurn вызывается после инструментов (+ попытка steer): при stop=true цикл завершается без обработки follow-up и без следующего вызова LLM.

type SteerMessage 

type SteerMessage func() (msg ai.Message, ok bool)

SteerMessage вставляет user-сообщение после инструментов (поддерживает изображения). Перекрывает SteerFn, если задан.

type StreamFn 

type StreamFn func(ctx context.Context, req ai.ChatRequest) (<-chan ai.ChatEvent, error)

StreamFn подменяет вызов Registry.Chat (например HTTP-прокси). Если nil, Loop использует Registry.Get().Chat.

type ToolCallOutcome 

type ToolCallOutcome struct {
	Call      ai.ToolCall
	Result    tools.Result
	Err       error
	Terminate bool // terminate — batch останавливается, когда все true
}

ToolCallOutcome — один результат выполненного инструмента в порядке вызовов assistant.

func ExecuteToolCalls 

func ExecuteToolCalls(
	ctx context.Context,
	rt *tools.Runtime,
	calls []ai.ToolCall,
	mode ToolExecutionMode,
	onProgress func(call ai.ToolCall, partial string),
) []ToolCallOutcome

ExecuteToolCalls выполняет tool calls по порядку (sequential) или параллельно. Результаты всегда возвращаются в том же порядке, что и вызовы. onProgress может быть nil; при parallel progress best-effort для каждого вызова.

type ToolExecutionMode 

type ToolExecutionMode string

ToolExecutionMode — последовательное или параллельное выполнение tool calls в одном ходе assistant. 

const (
	ToolExecutionSequential ToolExecutionMode = "sequential"
	ToolExecutionParallel   ToolExecutionMode = "parallel"
)

type ToolResult 

type ToolResult struct {
	CallID         string
	Name           string
	Content        string
	Error          string
	FullOutputPath string
	Truncated      bool
}

ToolResult — наблюдение за завершённым вызовом инструмента.

type TransformContext 

type TransformContext func(messages []ai.Message) []ai.Message

TransformContext — опциональный хук перед ConvertToLlm.

type TurnDecision 

type TurnDecision int

TurnDecision управляет потоком цикла после финализации хода assistant. 

const (
	// TurnExecuteTools выполняет вызовы инструментов (по умолчанию, если они есть).
	TurnExecuteTools TurnDecision = iota
	// TurnDone останавливает цикл (отправляет done с StopReason, если ещё не отправлен).
	TurnDone
	// TurnContinue пропускает инструменты и начинает следующую итерацию (например, пустой toolUse).
	TurnContinue
	// TurnRejectTools записывает результаты инструментов с ошибкой и продолжает (усечение по length).
	TurnRejectTools
	// TurnAbort останавливается после пути ошибки (ProcessStream/хуки уже отправили события).
	TurnAbort
)

Source Files

View all Source files

Directories

Path Synopsis
Package harness — helpers компактирования и system prompt для агентов.
 Package harness — helpers компактирования и system prompt для агентов.
Package hooks — in-process шина хуков агента (имена событий и Bus).
 Package hooks — in-process шина хуков агента (имена событий и Bus).
Package proxy маршрутизирует вызовы LLM через HTTP SSE.
 Package proxy маршрутизирует вызовы LLM через HTTP SSE.
Package session — JSONL-хранилище сессий, дерево веток и компактирование.
 Package session — JSONL-хранилище сессий, дерево веток и компактирование.
Package tools — runtime встроенных инструментов агента и выбор активного набора.
 Package tools — runtime встроенных инструментов агента и выбор активного набора.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.