Documentation
¶
Overview ¶
Package agentrun wires an agent, a machine, and optional blocks into a runnable pipeline. One New validates the transition matrix, the tool names, the budget, and the option combinations before it builds anything. One Run method drives the wired run. Store, Ask, and Artifacts compose through the built ack chain, which runs each gated step's tool by ID and confirms its ack. See ../docs/plans/agentrun.md and ../docs/packages/agentrun.md.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrNoAgent = errors.New("agentrun: agent is required") ErrNoMachine = errors.New("agentrun: machine is required") ErrNoResolver = errors.New("agentrun: Wait or Tools is required") ErrAmbiguousWait = errors.New("agentrun: Wait and Tools both set; set one") ErrNoTools = errors.New("agentrun: Scope, Store, Ask, or Artifacts needs Tools") ErrNoRecipient = errors.New("agentrun: Ask needs AskTo") ErrResultNotText = errors.New("agentrun: tool result is not a string") ErrReceiverEmpty = errors.New("agentrun: Receiver signer is empty") // ErrArgumentDecode is chain's error when the resolved tool's // DecodeArguments rejects the step's payload bytes. Test with // errors.Is. ErrArgumentDecode = errors.New("agentrun: tool arguments failed to decode") // ErrArtifactsInconsistent is Validate's error when an Artifacts // value's current values and run history disagree. Test with // errors.Is. ErrArtifactsInconsistent = errors.New("agentrun: artifacts state is inconsistent") )
Sentinel errors for New and Run; test with errors.Is. The matrix and budget checks wrap their own errors instead, naming the invalid value.
Functions ¶
func PayloadOf ¶
PayloadOf builds a flow.PayloadFrom closure that reads one step's artifact from a. The closure ignores its record argument and returns the stored string, or "" when a holds no value for step yet. For a step repeated inside a loop it returns the latest iteration's result.
func ValidateMatrix ¶
func ValidateMatrix(plan *flow.Definition, m *machine.Definition) error
ValidateMatrix checks that the plan's transition rows exist in m. It simulates the runner's declaration-order scan on the all-run path, so each step's rows start from the statuses the walk can rest on, not from the machine's initial status: sequential roots and siblings chain. For every such status the machine must hold exactly one row From=p To=target. Zero rows and two rows both fail, naming the step, the source, and the target. It recurses into every Sub child at every depth: a child Run starts from the machine's initial status, so the child's own walk is checked the same way. A Loop step that can run a second iteration also needs a re-entry row between every pair of distinct child finals. It is a static check; it does not prove the walk never aborts. Route exclusions, skipped needs, and forward-type mismatches can still abort mid-run after New passes. A loop landing the same final twice cannot: the equal-standing re-entry needs no row.
Types ¶
type Artifacts ¶
type Artifacts struct {
// contains filtered or unexported fields
}
Artifacts records each gated step's tool result by step ID. A step repeated inside a loop overwrites the entry, so the bare ID always holds the latest iteration's result. Every run also appends to a per-step history, so a caller can read earlier failures and rejections through History. Build a zero value with &Artifacts{}; Set initializes the maps on first use. It is safe for concurrent use.
func DecodeArtifacts ¶
DecodeArtifacts parses JSON produced by Encode and validates the result. The returned *Artifacts is ready for Get, History, Set, SetRun, and a later Encode.
func (*Artifacts) Encode ¶
Encode serializes a's current values and run history to JSON. It validates first. It is safe for concurrent use; a concurrent Set or SetRun blocks until Encode returns. A nil a encodes as the JSON of an empty wireArtifacts and never touches the mutex.
func (*Artifacts) Get ¶
Get returns the value stored under step and whether step held one. A nil Artifacts reads as empty.
func (*Artifacts) History ¶
History returns every recorded run of step, in run order. A nil Artifacts or an unknown step reads as empty. The caller owns the returned slice.
func (*Artifacts) Set ¶
Set stores value under step, replacing any earlier value, and appends one Run to the step's history.
func (*Artifacts) SetRun ¶
SetRun is Set with the producing message's ID recorded on the history entry. An empty msgID records the entry without one.
type Options ¶
type Options struct {
// Agent is the composed agent to drive. Required.
Agent *agent.Agent
// Machine is the status model the plan targets. Required.
Machine *machine.Definition
// Receiver is the ack From identity. It defaults to Agent.Signer().
Receiver *identity.Identity
// Bus receives the agent's events. Built and subscribed when nil.
Bus *events.Bus
// Tools drives the built ack chain, which runs tools by step ID.
Tools *tools.Registry
// Scope narrows the tools the chain calls. It needs Tools.
Scope *tools.Scope
// Store receives each gated step's result. It needs Tools.
Store *memory.Store
// Ask routes an escalated step to a human. It needs Tools.
Ask channel.Notifier
// AskTo names the human that answers Ask. It needs Ask.
AskTo string
// Artifacts records each gated step's result. It needs Tools.
Artifacts *Artifacts
// Room stamps onto each built message. Empty leaves Room zero.
Room string
// Budget gates each gated step's context fit. Optional.
Budget *contextbudget.Limits
// Monitor beats each gated step's id. Optional.
Monitor *heartbeat.Monitor
// Hooks observes and gates the run through the hooks registry.
// PointPreTool fires before each gated step's tool and vetoes;
// a veto fails the step. PointPostTool fires after each ack
// confirms, including an Ask round trip's confirmed ack. Both
// fire only with Tools: the Wait resolver runs no tool chain.
// PointStop fires with the final status once the walk ends, with
// either resolver. Optional.
Hooks *hooks.Registry
// Tracer opens one root span per run and one child span per
// gated step's tool call. Optional.
Tracer *trace.Tracer
// Wait resolves each gated step's ack. It is mutually exclusive
// with Tools.
Wait agent.AckWait
}
Options declares the blocks one New call wires into a Runner. The Agent and Machine fields are required; the rest are optional. Wait and Tools are mutually exclusive ack resolvers; one of them must be set.
type Run ¶
Run is one recorded result of one step run. MessageID is the signed message's ID, which carries the "#N" counter for a step repeated inside a loop.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner carries the blocks New validated and wired. Build it with New; the fields stay unexported.
func New ¶
New validates opts, then wires the resolved blocks into a Runner. It runs every check in a fixed order and returns the first failure. Checks: Agent and Machine non-nil; Wait and Tools not both set; one of them set; Scope, Store, Ask, and Artifacts each need Tools; Ask needs a non-empty AskTo; a set Budget passes its own Validate; the transition matrix passes ValidateMatrix; and, with Tools set, every Confirm-gated step ID resolves in the registry. New subscribes one no-op handler to the three agent event names on the resolved bus, then returns it through Runner.Bus.
func (*Runner) Bus ¶
Bus returns the resolved event bus New subscribed and wired. Callers add their own handlers through Bus().Subscribe for events the run emits.
func (*Runner) Run ¶
func (r *Runner) Run(ctx context.Context, threadID string, in machine.InOut) (machine.Status, machine.InOut, error)
Run drives the wired agent through the wired machine. threadID names the one envelope thread the run's step messages share; an empty threadID fails before any block runs, wrapping agent.ErrNoThread. in is the starting record. Run returns the final status, the final record, and the first error. A wired Tracer opens one root span for the run and child spans for every gated step's tool call. A wired Hooks registry fires PointPreTool before each tool call, PointPostTool after the ack confirms, and PointStop with the final status once the walk ends, success or failure.
Source Files