Skip to documentation
Documentation navigation

Documentation navigation

Documentation / guides

Declare delegates

Freeze the reachable delegation topology in Loop definitions.

developer

Declare a delegate on the parent Loop, then register both definitions with the Rig. WithDelegates is additive and duplicate names are removed when the Loop definition freezes. WithDelegation is a singleton option.

// The definitions are immutable after Define returns.
worker, err := loop.Define(
	loop.WithName("worker"),
	loop.WithInference(client, workerModel),
)
if err != nil {
	return err
}

orchestrator, err := loop.Define(
	loop.WithName("orchestrator"),
	loop.WithInference(client, coordinatorModel),
	loop.WithDelegates("worker"),
	loop.WithDelegation(loop.Delegation{Style: loop.DelegationManaged}),
)
if err != nil {
	return err
}

// store is an initialized session store owned by the application.
runtime, err := rig.Define(
	rig.WithLoops(orchestrator, worker),
	rig.WithPrimers("orchestrator"),
	rig.WithSessionStore(store),
)
if err != nil {
	return err
}
_ = runtime

Loop-level declarations

APIExact behavior
loop.WithDelegates(names ...identity.AgentName) loop.OptionAdds allowed target names. The option copies its input; Define freezes and deduplicates the result.
loop.WithDelegation(policy loop.Delegation) loop.OptionSets one DelegationStyle; a second use is rejected.
Definition.Delegates() []identity.AgentNameReturns a defensive copy of the frozen names.
Definition.Delegation() loop.DelegationReturns the frozen style.

DelegationSyncOnly permits only a DelegateStart that waits for its response. DelegationManaged permits start, send, interrupt, and status, with either waiting or background delivery subject to the request and ownership rules.

Proof: Loop delegation options and definition freeze and definition tests.

Rig graph validation

At rig.Define, names are checked across the complete graph:

CheckResult
Duplicate or blank Loop nameRig definition error.
Delegate name absent from WithLoopsRig definition error.
A Loop unreachable from WithPrimersRig definition error.
Duplicate primer or invalid active primerRig definition error.

The Loop definition’s policy revision includes sorted delegate names and the delegation style, so changing authority changes the definition identity. A target does not need to be known while the standalone Loop is being defined; the Rig is the boundary that can validate the target set.

Proof: Rig definition validation and topology reachability tests.

Reachability and authority

The graph is directed. If orchestrator declares worker, the runtime can create worker as a direct child. worker cannot use the orchestrator as a target unless its own definition declares that name, and a parent controller cannot address a sibling or ancestor by guessing an ID.

%%{init: {"theme":"dark"}}%%
flowchart LR
    A[orchestrator definition] -->|WithDelegates worker| B[worker definition]
    B -->|its own declarations only| D[worker children]
    A -.-> C[sibling or ancestor]
    C -.->|controller refuses| A

Proof: scoped controller ownership checks and delegation ownership tests.

Source and proof

← back to documentation