Documentation
¶
Overview ¶
Package agentloop provides a reusable stateless agent loop.
Run() executes one agent loop iteration: prompt → LLM → tool calls → response. The caller provides conversation history, a system prompt, tools, and an optional sandbox env. No persistence — the caller receives StepMessages and handles storage.
Plane: shared
Index ¶
Constants ¶
const DefaultMaxSteps = 30
DefaultMaxSteps is the fallback max steps when Config.MaxSteps is 0.
const DefaultMaxTokens = 16384
DefaultMaxTokens is the fallback max output tokens when Config.MaxTokens is 0.
Variables ¶
This section is empty.
Functions ¶
func BuildSystemPrompt ¶
func BuildSystemPrompt(data PromptData) (string, error)
BuildSystemPrompt renders the default system prompt with runtime context. The result is the base prompt — consumers append their own instructions after this.
Types ¶
type Callbacks ¶ added in v1.1.0
type Callbacks struct {
// OnDelta is called with each text delta as Claude streams its response.
OnDelta func(text string)
// OnToolStart is called when the agent selects a tool, before execution begins.
// Fires in the order: OnToolStart → tool executes → OnToolResult (internal).
// Use this to show progress indicators (e.g. "Using flicknote…").
OnToolStart func(toolName string)
}
Callbacks holds optional streaming callbacks for the agent loop. All fields are nil-safe — unset callbacks are simply not called.
type Config ¶
type Config struct {
Provider fantasy.Provider
Model string
SystemPrompt string
Tools []fantasy.AgentTool
MaxSteps int // 0 means use default (DefaultMaxSteps)
MaxTokens int // 0 means use default (DefaultMaxTokens)
SandboxEnv []string // passed to sandbox ExecConfig
AllowedPaths []string // absolute dirs the read/glob/grep tools may access
TreeThreshold int // chars — content above this returns tree by default; 0 = use default (5000)
}
Config holds everything needed to run one agent loop iteration.
type PromptData ¶
type PromptData struct {
WorkingDir string
Platform string
Date string
AllowedPaths []string
Tools []ToolInfo
}
PromptData holds the runtime context used to render the default system prompt.
type RunResult ¶
type RunResult struct {
Response string // final text response (accumulated assistant text)
Steps []StepMessage // all messages generated (for persistence by caller)
Result *fantasy.AgentResult
}
RunResult contains the agent's output after a loop completes.
func Run ¶
func Run( ctx context.Context, cfg Config, history []fantasy.Message, prompt string, cbs Callbacks, ) (*RunResult, error)
Run executes one agent loop: prompt → LLM → tool calls → response. Stateless — no DB, no conversation persistence. The caller handles that. cbs carries optional streaming callbacks; zero value disables all callbacks.
type StepMessage ¶
type StepMessage struct {
Role StepRole // StepRoleAssistant or StepRoleTool
Content string // text content
ToolCalls []ToolCallInfo // for assistant messages with tool use
ToolCallID string // for tool result messages
Timestamp time.Time
}
StepMessage represents one message generated during the agent loop. Richer than fantasy.Message — includes tool call metadata for persistence.
type StepRole ¶
type StepRole string
StepRole represents the role of a message step in the agent loop.
type ToolCallInfo ¶
type ToolCallInfo struct {
ID string
Name string
Input json.RawMessage // JSON-encoded tool input
}
ToolCallInfo carries tool call metadata for persistence.
Source Files
Directories