Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ else is additive. See the [v5 → v6 migration guide](internal/website/docs/guid
- **Agent guardrails** — `MaxSteps` (stop on count), `LoopLimit` (stop repeated no-progress calls; on by default), and `ApproveTool` (human-in-the-loop / policy gate before each action), enforced at the one point every tool call passes through. (`agent/`, guide + blog)
- **Pluggable agent memory & custom tools** — durable store-backed conversation memory by default, swappable via `AgentMemory`; register any function as a tool with `AgentTool`.
- **Workflows (`micro.NewFlow`)** — event-driven orchestration that maps to Anthropic's workflow/agent split: an event triggers a deterministic step (or ordered durable steps), or dispatches to an agent with `FlowAgent`. (`flow/`)
- **Flow loops (`FlowLoop`)** — a flow step that runs a body step repeatedly, carrying state across passes, until a stop condition is met or a hard iteration cap is hit. Stop on a code-defined predicate (`FlowUntil`) or let the model judge it done (`FlowUntilLLM` — the supervised "Ralph" loop); `FlowLoopMax` is the guardrail that guarantees termination, and `FlowOnIteration` reports progress. (`flow/loop.go`, `examples/flow-loop/`, guide)
- **x402 payments** — opt-in per-call payments for tools via the x402 standard, with a pluggable facilitator and a consumer-side client + budget; the MCP gateway can advertise and require payment per tool. (`wrapper/x402/`, guide + blog)
- **Scoped store state** — `store.Scope(s, database, table)` returns a store handle that confines every operation to a database/table without mutating the shared store (unlike `Init(Table(...))`, which is process-global and races between co-located components). Services, agents, and flows now each keep their state in their own table (`service/{name}`, `agent/{name}`, `flow/{name}`); the service path replaces the old `Init(store.Table(name))` global mutation with a scoped handle.
- **Flow discovery & history CLI** — running flows now register in the registry as `type=flow` (and deregister on `Stop`), so they're discoverable like agents: `micro flow list` shows running flows, `micro flow runs <name>` shows a flow's durable run history from the store, and `micro agent history <name>` shows an agent's stored conversation. Live state comes from the registry; durable history from the scoped store.
Expand Down
71 changes: 71 additions & 0 deletions examples/flow-loop/main.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
// Agentic Loop — keep working until the goal is met, with a guaranteed ceiling
//
// The "loop" pattern from agentic AI: instead of one shot, run a step over
// and over until the goal is reached, letting it decide when to stop — but
// always bounded by a hard iteration cap (the guardrail) so it can never run
// away, or run up an unbounded bill.
//
// flow.Loop is just a flow step, so it composes with the normal checkpointed
// step engine. This example needs no LLM key: the body is a plain func that
// "improves a draft" each pass, and a code-defined Until stops it once the
// draft is good enough — capped by FlowLoopMax. In a real flow the body would
// be micro.FlowDispatch("coder") (an agent) or micro.FlowLLM(...), and the
// stop check micro.FlowUntilLLM("Is the work complete?") — the supervised
// "Ralph" loop, where the model decides it's done but the cap still bounds it.
package main

import (
"context"
"fmt"

"go-micro.dev/v6"
)

// Draft is the payload carried across iterations via State.Set / State.Scan.
type Draft struct {
Text string `json:"text"`
Quality int `json:"quality"` // 0..100, improved each pass
}

// improve is one loop pass: it refines the draft a bit. In a real flow this
// would be an agent or an LLM turn; here it's deterministic so the example
// runs offline.
func improve(_ context.Context, in micro.FlowState) (micro.FlowState, error) {
var d Draft
_ = in.Scan(&d)
d.Quality += 30
d.Text = fmt.Sprintf("draft refined (quality %d)", d.Quality)
return in, in.Set(d)
}

func main() {
const goodEnough = 90

f := micro.NewFlow("refine",
micro.FlowSteps(
micro.FlowStep{Name: "improve", Run: micro.FlowLoop(
improve,
// Stop early once the draft is good enough...
micro.FlowUntil(func(_ context.Context, s micro.FlowState, iter int) (bool, error) {
var d Draft
_ = s.Scan(&d)
fmt.Printf(" pass %d → quality %d\n", iter, d.Quality)
return d.Quality >= goodEnough, nil
}),
// ...but never run the body more than 10 times (the ceiling).
micro.FlowLoopMax(10),
)},
),
micro.FlowDeleteOnSuccess(),
)

fmt.Println("refining until quality >=", goodEnough)
if err := f.Execute(context.Background(), `{"text":"initial draft","quality":0}`); err != nil {
fmt.Println("flow error:", err)
return
}

for _, r := range f.Results() {
fmt.Printf("\ndone: %s\n", r.Answer)
}
}
151 changes: 151 additions & 0 deletions flow/loop.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
package flow

import (
"context"
"fmt"
"strings"

"go-micro.dev/v6/ai"
)

// LoopCondition decides whether a Loop should stop, given the latest state
// and the iteration just completed (1-based). Returning true ends the loop.
type LoopCondition func(ctx context.Context, state State, iter int) (bool, error)

// LoopOptions configure a Loop. Max is the hard iteration cap — the ceiling
// that guarantees the loop always terminates, however the stop is decided.
// Until and UntilLLM are the optional early-stop checks.
type LoopOptions struct {
Max int
Until LoopCondition
UntilLLM string
OnIter func(iter int, state State)
}

// LoopOption configures a Loop.
type LoopOption func(*LoopOptions)

// LoopMax sets the hard iteration cap — the budget guardrail. The loop never
// runs the body more than n times, so it always terminates even when the
// stop condition never fires. Default 10.
func LoopMax(n int) LoopOption { return func(o *LoopOptions) { o.Max = n } }

// Until stops the loop when cond returns true after an iteration — a
// deterministic, code-defined exit condition.
func Until(cond LoopCondition) LoopOption { return func(o *LoopOptions) { o.Until = cond } }

// UntilLLM stops the loop when the flow's model judges the goal met. After
// each iteration it asks the model the question with the latest state and
// stops on an affirmative answer — the agent decides when it's done (the
// supervised "Ralph" loop), while LoopMax guarantees termination. Requires a
// flow model (set Provider/APIKey).
func UntilLLM(question string) LoopOption { return func(o *LoopOptions) { o.UntilLLM = question } }

// OnIteration runs fn after each iteration — useful for logging progress or
// persisting intermediate state.
func OnIteration(fn func(iter int, state State)) LoopOption {
return func(o *LoopOptions) { o.OnIter = fn }
}

// Loop returns a StepFunc that runs body repeatedly until a stop condition is
// met or the iteration cap is reached, whichever comes first — the agentic
// "loop": keep working until the goal is done, with a guaranteed ceiling so
// it can never run away.
//
// Compose it as a flow step. The carried State flows from one pass to the
// next, so each iteration sees the previous result:
//
// flow.New("refactor",
// flow.Provider("anthropic"),
// flow.Steps(
// flow.Step{Name: "improve", Run: flow.Loop(
// flow.Dispatch("coder"),
// flow.UntilLLM("Is the refactor complete with no duplicated abstractions left?"),
// flow.LoopMax(5),
// )},
// ),
// )
//
// The loop runs as a single flow step: the flow checkpoints the loop's
// outcome, and a resume re-enters the step, so loop bodies should be safe to
// repeat. Use OnIteration to record per-pass progress. If the cap is hit
// before the stop condition fires, the loop returns the latest state rather
// than erroring — the guardrail did its job.
func Loop(body StepFunc, opts ...LoopOption) StepFunc {
o := LoopOptions{Max: 10}
for _, op := range opts {
op(&o)
}
if o.Max <= 0 {
o.Max = 10
}
return func(ctx context.Context, in State) (State, error) {
if body == nil {
return in, fmt.Errorf("flow: Loop requires a body step")
}
cur := in
for iter := 1; iter <= o.Max; iter++ {
out, err := body(ctx, cur)
if err != nil {
return cur, fmt.Errorf("loop iteration %d: %w", iter, err)
}
cur = out
if o.OnIter != nil {
o.OnIter(iter, cur)
}
done, err := loopDone(ctx, o, cur, iter)
if err != nil {
return cur, err
}
if done {
return cur, nil
}
}
return cur, nil
}
}

// loopDone evaluates the stop conditions: a code-defined Until predicate
// and/or an LLM judgement. Either firing stops the loop.
func loopDone(ctx context.Context, o LoopOptions, state State, iter int) (bool, error) {
if o.Until != nil {
done, err := o.Until(ctx, state, iter)
if err != nil || done {
return done, err
}
}
if o.UntilLLM != "" {
return askDone(ctx, o.UntilLLM, state)
}
return false, nil
}

// askDone asks the flow model whether the goal is met given the current
// state, and returns true on an affirmative reply — the supervised stop check.
func askDone(ctx context.Context, question string, state State) (bool, error) {
d := depsFrom(ctx)
if d == nil || d.model == nil {
return false, fmt.Errorf("flow: UntilLLM requires a flow model (set Provider/APIKey)")
}
prompt := fmt.Sprintf("%s\n\nLatest result:\n%s\n\nAnswer with only \"yes\" or \"no\".", question, state.String())
resp, err := d.model.Generate(ctx, &ai.Request{Prompt: prompt})
if err != nil {
return false, err
}
reply := resp.Answer
if reply == "" {
reply = resp.Reply
}
return isAffirmative(reply), nil
}

// isAffirmative reports whether a model reply reads as "yes/done".
func isAffirmative(s string) bool {
s = strings.ToLower(strings.TrimSpace(s))
for _, p := range []string{"yes", "done", "true", "complete", "finished"} {
if strings.HasPrefix(s, p) {
return true
}
}
return false
}
91 changes: 91 additions & 0 deletions flow/loop_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
package flow

import (
"context"
"strconv"
"testing"
)

// counter body: increments an integer carried in State.Data.
func counter() StepFunc {
return func(ctx context.Context, in State) (State, error) {
n, _ := strconv.Atoi(in.String())
in.Data = []byte(strconv.Itoa(n + 1))
return in, nil
}
}

func TestLoopUntil(t *testing.T) {
step := Loop(counter(),
Until(func(ctx context.Context, s State, iter int) (bool, error) {
n, _ := strconv.Atoi(s.String())
return n >= 3, nil
}),
LoopMax(100),
)
out, err := step(context.Background(), State{Data: []byte("0")})
if err != nil {
t.Fatal(err)
}
if out.String() != "3" {
t.Fatalf("expected 3, got %q", out.String())
}
}

func TestLoopMaxCapStops(t *testing.T) {
runs := 0
body := func(ctx context.Context, in State) (State, error) { runs++; return in, nil }
// condition never fires; the cap must stop it
step := Loop(body,
Until(func(ctx context.Context, s State, iter int) (bool, error) { return false, nil }),
LoopMax(5),
)
if _, err := step(context.Background(), State{}); err != nil {
t.Fatal(err)
}
if runs != 5 {
t.Fatalf("expected 5 iterations (cap), got %d", runs)
}
}

func TestLoopOnIteration(t *testing.T) {
var seen []int
body := func(ctx context.Context, in State) (State, error) { return in, nil }
step := Loop(body, LoopMax(3), OnIteration(func(iter int, s State) { seen = append(seen, iter) }))
if _, err := step(context.Background(), State{}); err != nil {
t.Fatal(err)
}
if len(seen) != 3 || seen[0] != 1 || seen[2] != 3 {
t.Fatalf("expected iterations [1 2 3], got %v", seen)
}
}

func TestLoopBodyError(t *testing.T) {
body := func(ctx context.Context, in State) (State, error) {
return in, context.Canceled
}
step := Loop(body, LoopMax(3))
if _, err := step(context.Background(), State{}); err == nil {
t.Fatal("expected error from body to propagate")
}
}

func TestIsAffirmative(t *testing.T) {
cases := []struct {
in string
want bool
}{
{"yes", true},
{"Yes, the goal is met.", true},
{"DONE", true},
{"complete", true},
{"no", false},
{"not yet", false},
{"", false},
}
for _, c := range cases {
if got := isAffirmative(c.in); got != c.want {
t.Errorf("isAffirmative(%q) = %v, want %v", c.in, got, c.want)
}
}
}
2 changes: 2 additions & 0 deletions internal/website/_data/navigation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ examples:
guides:
- title: Agents and Workflows
url: /docs/guides/agents-and-workflows.html
- title: Agent Loops
url: /docs/guides/agent-loops.html
- title: Plan & Delegate
url: /docs/guides/plan-delegate.html
- title: Agent Guardrails
Expand Down
Loading
Loading