Interface: AgentBuilder<TIn, TOut, THandle>

Defined in: builders/agent-builder.ts:28

Fluent builder for the universal LLM actor primitive (P.agent(id)).

Compiles to a passive, deeply frozen AgentNode with canonical roleKey derivation.

Extends

• AstBuilder<AgentNode<TIn, TOut, THandle>>

Type Parameters

Type Parameter	Default type	Description
TIn	unknown	Validated actor input payload type.
TOut	unknown	Validated actor output payload type.
THandle	unknown	Runtime handle type of the active isolation scope.

Methods

beforeStop()

beforeStop(...checks): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:132

Appends deterministic beforeStop checks verified whenever the agent emits a completion turn.

Failed checks reject the completion turn in-band and return structured diagnostics to the model.

Parameters

Parameter	Type	Description
...checks	readonly ( | MaybeBuilder<BuiltInCheckASTNode<THandle>> | readonly MaybeBuilder<BuiltInCheckASTNode<THandle>>[])[]	Check AST nodes or builders.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

canRaise()

canRaise(...interrupts): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:166

Declares voluntary interrupts the agent may raise via synthetic interrupt tool calls.

Exposes each declared InterruptNode as a callable tool in the agent's toolset.

Parameters

Parameter	Type	Description
...interrupts	readonly ( | MaybeBuilder<InterruptNode<unknown>> | readonly MaybeBuilder<InterruptNode<unknown>>[])[]	Interrupt definitions.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

capabilities()

capabilities(configure): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:174

Configures hierarchical orchestration capabilities (.fork(), .speculate(), .mutatePlan(), .escalate()).

Invokes configure with an AgentCapabilitiesBuilder<TIn, THandle> and stores the compiled node.

Parameters

Parameter	Type	Description
configure	($cap) => AgentCapabilitiesBuilder<TIn, THandle>	Capabilities configurator callback.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

grounding()

grounding(...sources): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:108

Appends grounding text or source-backed grounding documents to the agent's context.

Injected into the Turn-0 [ROLE_AND_SCOPE_CONTEXT] user frame in declaration order.

Parameters

Parameter	Type	Description
...sources	readonly ( | MaybeSource<string> | readonly MaybeSource<string>[])[]	Grounding strings or source AST nodes.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

input()

input<TNewIn>(schema): AgentBuilder<TNewIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:141

Binds the Zod validation schema for the agent's input payload.

Preserves all previously configured partitions, capabilities, and onInterrupt bindings.

Type Parameters

Type Parameter	Description
TNewIn	Validated actor input payload type.

Parameters

Parameter	Type	Description
schema	ZodType<TNewIn>	Zod schema validating agent input.

Returns

AgentBuilder<TNewIn, TOut, THandle>

New immutable agent builder.

---

instructions()

instructions(...sources): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:116

Appends role instruction text or source-backed prompt documents to the agent's context.

Injected into the Turn-0 [ROLE_AND_SCOPE_CONTEXT] user frame after role grounding.

Parameters

Parameter	Type	Description
...sources	readonly ( | MaybeSource<string> | readonly MaybeSource<string>[])[]	Instruction strings or source AST nodes.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

lessons()

lessons<TLessonIn>(lessons, options?): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:76

Mounts an empirical LessonsNode on this agent for recalling relevant lessons at session start.

Defaults recordOutcomes to true when options is omitted.

Type Parameters

Type Parameter	Default type	Description
TLessonIn	unknown	Query input payload type of lessons.

Parameters

Parameter	Type	Description
lessons	MaybeBuilder<LessonsNode<TLessonIn>>	Lessons AST node or builder.
options?	{ recordOutcomes?: boolean; }	Outcome attribution toggle (recordOutcomes: true default).
options.recordOutcomes?	boolean	-

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

model()

model(modelOrPool): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:49

Binds the LLM model or model pool powering this agent's turns.

Required before .toAST() can compile a valid AgentNode.

Parameters

Parameter	Type	Description
modelOrPool	| MaybeBuilder<ModelASTNode> | MaybeBuilder<PoolNode<ModelASTNode>>	Model or pool AST node.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

onChildInterrupt()

onChildInterrupt<TPayload>(interrupt, configure?): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:185

Registers an upward child-interrupt handler (.onChildInterrupt(interrupt, $intr => ...)).

Intercepts interrupt when raised inside a child fork and suspends the fork back to this parent agent, defaulting to .suspendAndReturnToParent() when configure is omitted.

Type Parameters

Type Parameter	Description
TPayload	Interrupt payload type.

Parameters

Parameter	Type	Description
interrupt	MaybeBuilder<InterruptNode<TPayload>>	Upward interrupt node or builder.
configure?	($intr) => ChildInterruptHandlerBuilder<TPayload>	Optional child interrupt configurator callback.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

onInterrupt()

onInterrupt<TPayload>(interrupt, configure): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:198

Registers an actor-level default interrupt handler preserved across .withPolicy() and .withTools() clones.

Evaluated when interrupt is raised and no step-level .onInterrupt() override matches.

Type Parameters

Type Parameter	Description
TPayload	Interrupt payload type.

Parameters

Parameter	Type	Description
interrupt	MaybeBuilder<InterruptNode<TPayload>>	Target interrupt node or builder.
configure	($intr) => AstBuilder<InterruptHandlerNode<TIn, TPayload, THandle>>	Interrupt edge configurator callback.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

output()

output<TNewOut>(schema): AgentBuilder<TIn, TNewOut, THandle>;

Defined in: builders/agent-builder.ts:158

Binds the Zod validation schema for the agent's structured output payload.

Validated automatically during the beforeStop completion gate.

Type Parameters

Type Parameter	Description
TNewOut	Validated actor output payload type.

Parameters

Parameter	Type	Description
schema	ZodType<TNewOut>	Zod schema validating agent output.

Returns

AgentBuilder<TIn, TNewOut, THandle>

New immutable agent builder.

---

partitions()

partitions(extractor): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:149

Binds an optional synchronous extractor mapping TIn to ResolutionContext.activePartitions.

Determines which topology contracts and partition-scoped rules are injected at Turn 0.

Parameters

Parameter	Type	Description
extractor	(input) => readonly string[]	Partition ID extractor callback.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

policy()

policy(policy): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:92

Binds the capability and sandbox PolicyNode governing tool execution and quantitative limits.

Evaluates pre-flight and post-flight guard clauses on every tool invocation.

Parameters

Parameter	Type	Description
policy	MaybeBuilder<PolicyNode<THandle>>	Policy AST node or builder.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

prefixGroup()

prefixGroup(group): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:41

Binds a shared PrefixGroupNode for byte-identical wire system prompts.

Pins shared grounding, instructions, and global rules into Slot 1 of the wire prompt.

Parameters

Parameter	Type	Description
group	MaybeBuilder<PrefixGroupNode>	Shared prefix group AST node or builder.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

rules()

rules(rules): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:66

Mounts a global and scoped RulesNode registry on this agent.

Evaluates scoped rules pre-flight on active partitions and post-call on tool effects.

Parameters

Parameter	Type	Description
rules	MaybeBuilder<RulesNode>	Rules AST node or builder.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

skills()

skills(...items): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:84

Mounts one or more inline SkillNode definitions or source-backed skill bundles.

Populates the Turn-0 skill catalog and unlocks the native activateSkill tool.

Parameters

Parameter	Type	Description
...items	readonly ( | MaybeBuilder<SkillNode<THandle>> | MaybeBuilder<SourceASTNode<readonly SkillNode<THandle>[]>> | readonly MaybeBuilder<SkillNode<THandle>>[])[]	Skills or skill bundle sources.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

timeoutMinutes()

timeoutMinutes(minutes): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:124

Sets the wall-clock timeout in minutes for the agent step.

Enforces an upper bound on the agent's total execution duration.

Parameters

Parameter	Type	Description
minutes	number	Positive wall-clock timeout in minutes.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

toAST()

toAST(): AgentNode;

Defined in: ast/ast-builder.ts:20

Compiles the current builder configuration into a deeply frozen passive AST node.

Validates required builder invariants at compilation time and returns an immutable plain-object AST representation containing zero execution methods.

Returns

AgentNode

Deeply frozen passive AST node.

Inherited from

AstBuilder.toAST

---

tools()

tools(...items): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:100

Mounts always-unlocked ToolASTNode entries directly on this base agent.

Base tools are included in the base agent's id role without appending +tools:... to roleKey.

Parameters

Parameter	Type	Description
...items	readonly ( | MaybeBuilder<BuiltInToolASTNode<THandle>> | readonly MaybeBuilder<BuiltInToolASTNode<THandle>>[])[]	Tools or tool arrays.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

topology()

topology<TPart>(topology): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:58

Binds a relational TopologyNode whose live partition contracts are injected into the Turn-0 context frame.

Enables automatic partition contract injection and epoch tracking for active partitions.

Type Parameters

Type Parameter	Default type	Description
TPart extends string	string	Literal partition identifier union of topology.

Parameters

Parameter	Type	Description
topology	MaybeBuilder<TopologyNode<TPart>>	Relational topology AST node or builder.

Returns

AgentBuilder<TIn, TOut, THandle>

New immutable agent builder.

---

withPolicy()

withPolicy(newPolicy): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:206

Clones this agent with newPolicy while preserving roleKey, .prefixGroup(), .partitions(), and .onInterrupt() handlers.

Produces a new immutable AgentBuilder without mutating the source agent definition.

Parameters

Parameter	Type	Description
newPolicy	MaybeBuilder<PolicyNode<THandle>>	Replacement policy node or builder.

Returns

AgentBuilder<TIn, TOut, THandle>

Cloned immutable agent builder.

---

withTools()

withTools(...extraTools): AgentBuilder<TIn, TOut, THandle>;

Defined in: builders/agent-builder.ts:214

Clones this agent with additional tools and derives the canonical order-independent roleKey ("${id}+tools:${sortedNames}").

Preserves all existing configuration while appending extraTools to the cloned agent.

Parameters

Parameter	Type	Description
...extraTools	readonly ( | MaybeBuilder<BuiltInToolASTNode<THandle>> | readonly MaybeBuilder<BuiltInToolASTNode<THandle>>[])[]	Additional tools to mount.

Returns

AgentBuilder<TIn, TOut, THandle>

Cloned immutable agent builder with updated roleKey.

Properties

Property	Modifier	Type	Description	Defined in
id	readonly	string	Unique identifier of the base agent definition.	builders/agent-builder.ts:31
roleKey	readonly	string	Canonical role key (id or "${id}+tools:${sortedExtraToolNames.join(',')}").	builders/agent-builder.ts:33