AxAgent
Pipeline-based coordinator. Every run walks the same static sequence:
distiller (RLM actor) → executor (RLM actor) ↓ responder (Synthesizer)
The distiller’s final(request, evidence) payload feeds the executor as
{executorRequest, distilledContext}. When no contextFields are declared,
the distiller still acts as the context-understanding/request-normalization
stage over the original inputs.
This is the primary user-facing class. ActorAgentRLM and Synthesizer
are exported for callers that need direct per-instance control.
Type Parameters
| Type Parameter |
|---|
IN extends AxGenIn |
OUT extends AxGenOut |
Implements
AxAgentic<IN,OUT>
Constructors
Constructor
new AxAgent<IN, OUT>(init: Readonly<{
agentIdentity?: Readonly<AxAgentIdentity>;
agentModuleNamespace?: string;
ai?: Readonly<AxAIService>;
judgeAI?: Readonly<AxAIService>;
signature: | string
| Readonly<AxSignatureConfig>
| Readonly<AxSignature<IN, OUT>>;
}>, options: Readonly<AxAgentOptions<IN>>): AxAgent<IN, OUT>;Parameters
| Parameter | Type |
|---|---|
init | Readonly<{ agentIdentity?: Readonly<AxAgentIdentity>; agentModuleNamespace?: string; ai?: Readonly<AxAIService>; judgeAI?: Readonly<AxAIService>; signature: | string | Readonly<AxSignatureConfig> | Readonly<AxSignature<IN, OUT>>; }> |
options | Readonly<AxAgentOptions<IN>> |
Returns
AxAgent<IN, OUT>
Properties
| Property | Modifier | Type | Description |
|---|---|---|---|
autoUpgradeResolved | readonly | AxResolvedAutoUpgrade | Resolved auto-upgrade config; also read by the responder-input helpers. |
distiller | readonly | ActorAgentRLM<any, any> | RLM actor that normalizes the request and distils context evidence. |
distillerAi? | readonly | Readonly<AxAIService<unknown, unknown, string>> | Per-stage AI service overrides. When set, the corresponding stage uses this AI service instead of the one passed positionally to forward(). forward(ai, ...) is the fallback when the stage-specific override is not defined. |
executor | readonly | ActorAgentRLM<any, any> | RLM actor that runs tools / discovery with the pre-distilled context. |
executorAi? | readonly | Readonly<AxAIService<unknown, unknown, string>> | - |
executorExcludeFields | readonly | Set<string> | Field names stripped from executor inputs (from executorOptions.excludeFields). |
responder | readonly | Synthesizer<OUT> | Synthesizer that produces the user’s output signature. Always present. |
responderAi? | readonly | Readonly<AxAIService<unknown, unknown, string>> | - |
responderExcludeFields | readonly | Set<string> | Field names stripped from responder inputs (from responderOptions.excludeFields). |
Accessors
primaryAgent
Get Signature
get primaryAgent(): ActorAgentRLM<any, any>;Backward-compat handle used by legacy access patterns: returns the actor
stage that “owns” the run-time forward — always the executor in
current pipeline shapes. Tests reach in via
agent.primaryAgent.actorProgram etc.
Returns
ActorAgentRLM<any, any>
Methods
_forwardForEvaluation()
_forwardForEvaluation<T>(
parentAi: T,
task: Readonly<AxAgentEvalTask<IN>>,
options?: Readonly<AxProgramForwardOptionsWithModels<T>>): Promise<AxAgentEvalPrediction<OUT>>;Internal
Used by the optimizer to evaluate a single dataset task end-to-end.
Type Parameters
| Type Parameter |
|---|
T extends Readonly<AxAIService<unknown, unknown, string>> |
Parameters
| Parameter | Type |
|---|---|
parentAi | T |
task | Readonly<AxAgentEvalTask<IN>> |
options? | Readonly<AxProgramForwardOptionsWithModels<T>> |
Returns
Promise<AxAgentEvalPrediction<OUT>>
_syncContextMapPrompt()
_syncContextMapPrompt(): void;Returns
void
_updateContextMapFromPipelineState()
_updateContextMapFromPipelineState(
ai: Readonly<AxAIService>,
state: Readonly<Record<string, any>>,
finalOutput?: unknown): Promise<void>;Parameters
| Parameter | Type |
|---|---|
ai | Readonly<AxAIService> |
state | Readonly<Record<string, any>> |
finalOutput? | unknown |
Returns
Promise<void>
_updatePlaybookFromPipelineState()
_updatePlaybookFromPipelineState(state: Readonly<Record<string, any>>): Promise<
| undefined
| AxAgentPlaybookUpdateResult>;Internal
Run-end failure learning for the attached playbook (see
AxAgentPlaybookConfig.learn): merge the stages’ deterministic failure
reports, gate on volume and signature novelty, then feed one bounded
playbook update whose curated rules land in the failures_to_avoid
section. Non-fatal by construction — playbook upkeep must never break the
completed user-facing run.
Public for the pipeline flow node and tests.
Parameters
| Parameter | Type |
|---|---|
state | Readonly<Record<string, any>> |
Returns
Promise<
| undefined
| AxAgentPlaybookUpdateResult>
addActorInstruction()
addActorInstruction(addendum: string): void;Append a standing instruction addendum to the executor actor’s prompt.
A separate additive channel from executorOptions.description and the
playbook injection, so the three never clobber each other. Process-local —
not serialized into AxAgentState.
Parameters
| Parameter | Type |
|---|---|
addendum | string |
Returns
void
applyOptimization()
applyOptimization(optimizedProgram: any): void;Parameters
| Parameter | Type |
|---|---|
optimizedProgram | any |
Returns
void
Implementation of
applyOptimizedComponents()
applyOptimizedComponents(updates: Readonly<Record<string, string>>): void;Apply a map of componentKey → newValue updates produced by an optimizer.
Each program filters keys belonging to itself and dispatches internally.
Unknown keys are silently ignored, which lets parents broadcast a single
map across the whole subtree.
Parameters
| Parameter | Type |
|---|---|
updates | Readonly<Record<string, string>> |
Returns
void
Implementation of
AxAgentic.applyOptimizedComponents
forward()
forward<T>(
ai: T,
values: IN & object,
options?: Readonly<AxAgentForwardOptions<T>>): Promise<OUT>;Run the agent once.
Type Parameters
| Type Parameter |
|---|
T extends Readonly<AxAIService<unknown, unknown, string>> |
Parameters
| Parameter | Type | Description |
|---|---|---|
ai | T | - |
values | IN & object | Signature inputs plus an optional memories array. Forward memories are visible from the first actor turn, merge with recalled entries by ID, and reset before the next call. |
options? | Readonly<AxAgentForwardOptions<T>> | - |
Returns
Promise<OUT>
Implementation of
getChatLog()
getChatLog(): readonly AxChatLogEntry[];Returns
readonly AxChatLogEntry[]
Implementation of
getContextMap()
getContextMap(): undefined | AxAgentContextMap;Returns
undefined | AxAgentContextMap
getFunction()
getFunction(): AxFunction;Returns
Implementation of
getId()
getId(): string;Returns
string
Implementation of
getOptimizableComponents()
getOptimizableComponents(): readonly any[];Enumerate all string-valued artifacts this program tree exposes for reflective optimization (instructions, signature descriptions, function names/descriptions, agent system prompts, etc.). Composite programs flat-map their children’s components and append their own.
The optimizer never walks the tree — traversal is encapsulated here.
Returns
readonly any[]
Implementation of
AxAgentic.getOptimizableComponents
getPlaybook()
getPlaybook():
| undefined
| AxAgentPlaybook<any, any>;The agent’s playbook handle, or undefined if none has been created.
Returns
| undefined
| AxAgentPlaybook<any, any>
getSignature()
getSignature(): AxSignature;Returns
Implementation of
getStagedUsage()
getStagedUsage(): object;Returns
object
| Name | Type |
|---|---|
ctx? | AxAgentUsage |
task | AxAgentUsage |
getState()
getState(): undefined | AxAgentState;Returns
undefined | AxAgentState
getTraces()
getTraces(): AxProgramTrace<IN, OUT>[];Returns
AxProgramTrace<IN, OUT>[]
Implementation of
getUsage()
getUsage(): AxAgentUsage;Returns
Implementation of
namedProgramInstances()
namedProgramInstances(): AxNamedProgramInstance<IN, OUT>[];Returns
AxNamedProgramInstance<IN, OUT>[]
Implementation of
AxAgentic.namedProgramInstances
namedPrograms()
namedPrograms(): object[];The distiller is reported under ctx.* and the executor / responder
pair under task.* so optimizer demo IDs and template-overrides keep
stable stage ownership.
Returns
object[]
optimize()
optimize(dataset: Readonly<AxAgentEvalDataset<IN>>, options?: Readonly<AxAgentOptimizeOptions<_IN, _OUT>>): Promise<AxAgentOptimizeResult<OUT>>;Parameters
| Parameter | Type |
|---|---|
dataset | Readonly<AxAgentEvalDataset<IN>> |
options? | Readonly<AxAgentOptimizeOptions<_IN, _OUT>> |
Returns
Promise<AxAgentOptimizeResult<OUT>>
playbook()
playbook(options?: Readonly<AxAgentPlaybookOptions>): AxAgentPlaybook<any, any>;The agent’s learned playbook — one evolving body of task knowledge bound
to an agent stage (the actor/task stage by default). It grows three ways:
continuously from each run (the playbook construction config),
on demand via .update(...), or from a task set via
.evolve(dataset, options) (verified by default). Unless apply is
false, the rendered playbook is injected into the live stage prompt.
Memoized — one playbook per agent. The evolution engine (ACE) is an
implementation detail.
Parameters
| Parameter | Type |
|---|---|
options? | Readonly<AxAgentPlaybookOptions> |
Returns
AxAgentPlaybook<any, any>
resetUsage()
resetUsage(): void;Returns
void
Implementation of
setContextMap()
setContextMap(map?:
| string
| AxAgentContextMapSnapshot
| AxAgentContextMap): void;Parameters
| Parameter | Type |
|---|---|
map? | | string | AxAgentContextMapSnapshot | AxAgentContextMap |
Returns
void
setDemos()
setDemos(demos: readonly (
| AxAgentDemos<IN, OUT>
| AxProgramDemos<IN, OUT>)[], options?: object): void;Parameters
| Parameter | Type |
|---|---|
demos | readonly ( | AxAgentDemos<IN, OUT> | AxProgramDemos<IN, OUT>)[] |
options? | { modelConfig?: Record<string, unknown>; } |
options.modelConfig? | Record<string, unknown> |
Returns
void
Implementation of
setId()
setId(id: string): void;Parameters
| Parameter | Type |
|---|---|
id | string |
Returns
void
Implementation of
setSignature()
setSignature(signature: AxSignatureInput): void;Parameters
| Parameter | Type |
|---|---|
signature | AxSignatureInput |
Returns
void
setState()
setState(state?: AxAgentState): void;Parameters
| Parameter | Type |
|---|---|
state? | AxAgentState |
Returns
void
stop()
stop(): void;Returns
void
streamingForward()
streamingForward<T>(
ai: T,
values: IN & object,
options?: Readonly<AxAgentStreamingForwardOptions<T>>): AxGenStreamingOut<OUT>;Run the agent once and stream its output.
Type Parameters
| Type Parameter |
|---|
T extends Readonly<AxAIService<unknown, unknown, string>> |
Parameters
| Parameter | Type | Description |
|---|---|---|
ai | T | - |
values | IN & object | Signature inputs plus an optional memories array with the same per-forward merge and reset semantics as forward(). |
options? | Readonly<AxAgentStreamingForwardOptions<T>> | - |
Returns
AxGenStreamingOut<OUT>
Implementation of
test()
test(
code: string,
values?: Partial<IN>,
options?: Readonly<{
abortSignal?: AbortSignal;
ai?: AxAIService<unknown, unknown, string>;
debug?: boolean;
}>): Promise<AxAgentTestResult>;Parameters
| Parameter | Type |
|---|---|
code | string |
values? | Partial<IN> |
options? | Readonly<{ abortSignal?: AbortSignal; ai?: AxAIService<unknown, unknown, string>; debug?: boolean; }> |
Returns
Promise<AxAgentTestResult>