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) SetSkillLoader(sl SkillLoader)
  • func (e *Engine) SetToolEventHandler(cb ToolEventHandler)
• 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) SetSkillLoader

func (e *Engine) SetSkillLoader(sl SkillLoader)

SetSkillLoader sets the optional skill loader callback.

func (*Engine) SetToolEventHandler

func (e *Engine) SetToolEventHandler(cb ToolEventHandler)

SetToolEventHandler sets the optional tool event callback for live streaming.

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.