agentloop

A perpetual autonomous-agent control loop for Go: a guarded finite-state machine driving Plan -> Execute -> Evaluate -> Improve, wrapped with a threshold-driven budget enforcer that can force the loop into cooldown mid-cycle when spend runs hot.

Zero dependencies outside the Go standard library.

Why

Long-running agent loops (an agent that plans, executes, evaluates its own output, and improves before looping back) need two things that are easy to get wrong by hand:

1. Guarded transitions. Not every state can go to every other state. agentloop encodes the valid transition table once and rejects anything else, so a bug elsewhere in your program can't accidentally skip evaluation or resume from a terminal state.
2. Budget-driven state coercion. An autonomous loop that spends money (LLM tokens, compute, API calls) needs a way to notice it's running hot and change its own behavior — not just log a warning after the fact. agentloop's BudgetEnforcer maps spend percentage to an action (continue / warn / cooldown / escalate / stop), and Controller wires that straight into a forced Cooldown transition.

Core pieces

• StateMachine — a thread-safe FSM over LoopState (Idle, Planning, Executing, Evaluating, Improving, Complete, Cooldown, Drain, Exit). Holds the standard transition table, records a full history of transitions, and notifies an OnChange callback after every successful move.
• BudgetEnforcer — tracks cumulative spend against a global cap and reports the highest-priority BudgetAction crossed: 80% -> warn, 90% -> cooldown, 95% -> escalate, 100% -> stop. A zero or negative budget means "unlimited."
• Controller — the high-level API. Wires per-state callbacks (OnEnterEvaluate, OnEnterImprove, OnPhaseChange, OnError) onto the state machine, exposes Start/Advance/Complete/Cancel for driving the happy path and graceful shutdown, and calls RecordSpend to feed the budget enforcer and force Cooldown when thresholds are breached.

Install

go get github.com/hairglasses-studio/agentloop

Usage

c := agentloop.NewController(100.0) // $100 budget

c.OnEnterEvaluate(func() error {
    // run your evaluation step; return an error to report via OnError
    return nil
})
c.OnEnterImprove(func() error {
    // run your improvement step
    return nil
})
c.OnPhaseChange(func(phase string) {
    fmt.Println("now in phase:", phase)
})
c.OnError(func(state agentloop.LoopState, err error) {
    log.Printf("callback failed in %s: %v", state, err)
})

if err := c.Start(); err != nil { // Idle -> Planning
    log.Fatal(err)
}

for c.State() != agentloop.StateComplete {
    // do the work for the current phase...
    c.RecordSpend(1.25) // may force a transition into Cooldown

    if c.State() == agentloop.StateCooldown {
        // back off, then recover into Planning
        if err := c.Start(); err != nil {
            log.Fatal(err)
        }
        continue
    }

    if err := c.Advance(); err != nil {
        break
    }
}

See example/main.go for a complete runnable program that drives the FSM through a mock plan/execute/evaluate/improve cycle, including a forced cooldown once the budget threshold is crossed.

Testing

go build ./...
go test ./...