supervise

README

supervise

Default workflow.Supervisor implementation for agentcore's supervision pipeline. Handles the two pluggable phases: deterministic drift detection (Reconcile) and LLM-driven verdict rendering (Supervise). The other three phases — COMMIT, EXECUTE, and POST — run inside the workflow package against the agent's model; only RECONCILE and SUPERVISE are swappable.

Usage

Wire into workflow.Runtime to supervise any node marked Supervise() or SuperviseByHuman():

import (
    "github.com/vinayprograms/agentcore/supervise"
    "github.com/vinayprograms/agentcore/workflow"
)

// Dedicated supervisor model — optional. When nil, the supervisor
// falls back to the agent's main model carried by SuperviseRequest.
sup := supervise.New(supervise.Config{
    Model: supervisorModel,
})

rt := &workflow.Runtime{
    Model:      agentModel,
    Supervisor: sup,
}

wf := workflow.New("pipeline").
    Add(workflow.Sequence("main").Steps(
        workflow.Goal("draft", "Write a proposal").
            Supervise(), // runs through the full 5-phase pipeline
        workflow.Convergence("refine", "Polish the text", 3).
            SuperviseByHuman(), // requires human approval
    ))

state, err := wf.Execute(ctx, rt, inputs)

Without a supervisor, unsupervised steps execute directly; supervised steps fail at Validate.

Reconcile

Deterministic, no LLM. Checks four signals from the agent's post-execution self-assessment:

Signal	Trigger produced
MetCommitment == false	commitment_not_met
Non-empty Deviations	deviation:<text> per entry
Non-empty Concerns	concern:<text> per entry
Non-empty Unexpected	unexpected:<text> per entry

Any trigger sets Escalate = true and the pipeline proceeds to SUPERVISE (for byLLM steps) or AskHuman (for byHuman steps). Clean execution short-circuits — no costly LLM call.

Supervise

LLM call against Config.Model (if set) or the agent's model (fallback). Receives the original goal, the pre/post checkpoints, and reconcile triggers. Renders one of four verdicts:

Verdict	Behavior
Continue	Accept output as-is
Reorient	Re-run EXECUTE with correction (bounded by MaxReorientAttempts)
AskHuman	Dispatch question on HumanCh; human response becomes correction
Halt	Terminate with the supervisor's reason

On parse failure (malformed JSON from the LLM), the verdict degrades to AskHuman so a human can resolve the ambiguous output.

Lifecycle

Stateless beyond the Config struct — no Close needed. The reorient counter and human-handshake orchestration live in the workflow package; this package only renders verdicts when called.

Documentation

Overview

Package supervise provides a default workflow.Supervisor implementation for the five-phase supervision pipeline (COMMIT → EXECUTE → POST → RECONCILE → SUPERVISE). Reconcile does deterministic drift detection against the pre/post checkpoints. Supervise calls a configured LLM to render a verdict (Continue, Reorient, AskHuman, or Halt).

Usage:

sup := supervise.New(supervise.Config{
    Model: supervisorModel, // optional; falls back to the agent's model
})
rt := &workflow.Runtime{
    Model:      agentModel,
    Supervisor: sup,
}

Index

• func New(cfg Config) workflow.Supervisor
• type Config

Functions

func New

func New(cfg Config) workflow.Supervisor

New returns a workflow.Supervisor backed by the given Config. The returned value satisfies the two-method interface defined by the workflow package; its concrete type is unexported so consumers program to the interface.

Types

type Config

type Config struct {
	// Model is the dedicated LLM for the SUPERVISE phase. When nil, the
	// supervisor falls back to the model carried by workflow.SuperviseRequest
	// (the agent's main model). Separate models let the supervisor reason
	// independently — a cheaper or thinking-enabled model, for example.
	Model llm.Model
}

Config holds the optional settings for a Supervisor. Zero-value is usable — both fields default to reasonable values.