loop

Documentation

Overview

Package loop implements the ReAct (Reasoning + Acting) agent loop.

Index

• type Engine
  • func New(client *llm.Client, registry *tool.Registry, maxIterations int, ...) *Engine
  • func (e *Engine) Run(ctx context.Context, task string) (string, error)
  • func (e *Engine) RunWithMessages(ctx context.Context, messages []llm.Message) (string, []llm.Message, error)
  • func (e *Engine) SetIterationCallback(cb IterationCallback)
  • func (e *Engine) SetMemoryPromptFunc(fn func() string)
  • func (e *Engine) SetSkillLoader(sl SkillLoader)
  • func (e *Engine) SetSkillVerbose(verbose bool)
  • func (e *Engine) SetToolEventHandler(cb ToolEventHandler)
• type IterationCallback
• type IterationInfo
• type SkillLoader
• type ToolEventHandler

Types

type Engine

type Engine struct {

	// PromptCaching enables Anthropic/OpenAI/DeepSeek prompt caching markers.
	// When enabled, the system prompt and first user message are annotated
	// with cache_control markers, and the system prompt is moved to the
	// dedicated "system" field for Anthropic compatibility.
	PromptCaching bool

	// Token accounting — accumulated across all iterations of the most recent run.
	// Reset on each Run/RunWithMessages call and read by callers (e.g. WebUI).
	TotalInputTokens  int
	TotalOutputTokens int

	// Cache metrics accumulated across all iterations.
	TotalCacheCreationTokens int // Anthropic: tokens written to cache
	TotalCacheReadTokens     int // Anthropic: tokens read from cache
	TotalCachedTokens        int // OpenAI: cached prompt tokens
	// contains filtered or unexported fields
}

Engine runs the agent loop: observe → think → act → repeat.

func New

func New(client *llm.Client, registry *tool.Registry, maxIterations int, systemMessage string, renderer *render.Renderer, maxContext int) *Engine

New creates a new loop Engine. maxContext is the model's maximum context window in tokens. Pass 0 for no limit enforcement.

func (*Engine) Run

func (e *Engine) Run(ctx context.Context, task string) (string, error)

Run executes the loop for a given task and returns the final response.

func (*Engine) RunWithMessages

func (e *Engine) RunWithMessages(ctx context.Context, messages []llm.Message) (string, []llm.Message, error)

RunWithMessages executes the agent loop starting from a pre-built message history. The messages must include the system prompt (if any), all prior conversation turns, and the new user message as the last entry. Returns the final answer plus the full updated message history so callers can persist it (e.g. to a session file).

Use this for multi-turn conversations: load the session, append the new user message, call RunWithMessages, then save the returned messages.

func (*Engine) SetIterationCallback

func (e *Engine) SetIterationCallback(cb IterationCallback)

SetIterationCallback sets the iteration progress callback. If nil, no callback is fired.

func (*Engine) SetMemoryPromptFunc

func (e *Engine) SetMemoryPromptFunc(fn func() string)

SetMemoryPromptFunc sets the optional memory prompt callback. When set, it is called before each LLM invocation to get fresh memory content. This ensures the agent sees the latest facts even if it modifies memory during a session.

func (*Engine) SetSkillLoader

func (e *Engine) SetSkillLoader(sl SkillLoader)

SetSkillLoader sets the optional skill loader callback.

func (*Engine) SetSkillVerbose

func (e *Engine) SetSkillVerbose(verbose bool)

SetSkillVerbose controls whether skill loading shows full banners (true) or condensed markers (false, default). Condensed saves context window space.

func (*Engine) SetToolEventHandler

func (e *Engine) SetToolEventHandler(cb ToolEventHandler)

SetToolEventHandler sets the optional tool event callback for live streaming.

type IterationCallback

type IterationCallback func(info IterationInfo)

IterationCallback is an optional callback invoked after each iteration of the agent loop. Used by Telegram/WebUI for progress reporting.

type IterationInfo

type IterationInfo struct {
	Turn                int           // current iteration (1-indexed)
	MaxTurns            int           // max iterations configured
	ToolNames           []string      // tools called this turn (duplicates possible)
	InputTokens         int           // cumulative input tokens
	OutputTokens        int           // cumulative output tokens
	CacheCreationTokens int           // cumulative cache creation tokens
	CacheReadTokens     int           // cumulative cache read tokens
	CachedTokens        int           // cumulative cached tokens (OpenAI)
	TotalLatency        time.Duration // cumulative wall time
	HasFinalAnswer      bool          // true when the agent reached a final answer
}

IterationInfo holds data about a single agent loop iteration, passed to the IterationCallback after each turn. Used for progress reporting.

type SkillLoader

type SkillLoader func(userInput string) string

SkillLoader is an optional callback that the loop engine calls before each LLM invocation to discover contextually relevant skills. The callback receives the latest user input and returns additional system context (formatted skill content) to inject, or empty string if no skills match.

type ToolEventHandler

type ToolEventHandler func(event string, name string, data string)

ToolEventHandler is an optional callback invoked for each tool execution during the agent loop — fires before (tool_call) and after (tool_result) each tool invocation. Used by the WebUI for live streaming of tool events.