ax-agent

name	ax-agent
description	This skill helps an LLM generate correct AxAgent code using @ax-llm/ax. Use when the user asks about agent(), child agents, namespaced functions, discovery mode, shared fields, llmQuery(...), RLM code execution, recursionOptions, or agent runtime behavior. For tuning and eval with agent.optimize(...), use ax-agent-optimize.
version	19.0.44

AxAgent Codegen Rules (@ax-llm/ax)

Use this skill to generate AxAgent code. Prefer short, modern, copyable patterns. Do not write tutorial prose unless the user explicitly asks for explanation.

Your job is not just to write valid code. Your job is to choose the smallest correct AxAgent shape for the user's needs:

• If the user wants a normal tool-using assistant, keep the config minimal.
• If the user wants long-running code execution, use RLM features deliberately.
• If the user wants delegated subtasks, decide whether they need plain llmQuery(...) or recursive advanced mode.
• If the user wants observability, add only the specific hooks or debug options that support that need.
• If the user is unsure, choose conservative defaults and avoid exotic options.

Use These Defaults

• Use agent(...), not new AxAgent(...).
• Prefer fn(...) for host-side function definitions instead of hand-writing JSON Schema objects.
• Prefer namespaced functions such as utils.search(...) or kb.find(...).
• Assume the child-agent module is agents unless agentIdentity.namespace is set.
• If functions.discovery is true, discover callables from modules before using them.
• In stdout-mode RLM, use one observable console.log(...) step per non-final actor turn.
• Prefer promptLevel: 'default' for normal use; use promptLevel: 'detailed' when you want extra anti-pattern examples and tighter teaching scaffolding in the actor prompt.
• Default to contextPolicy: { preset: 'checkpointed', budget: 'balanced' } for most RLM tasks.
• Prefer contextPolicy: { preset: 'adaptive', budget: 'balanced' } when older successful turns should collapse sooner while live runtime state stays visible.
• Prefer actorModelPolicy when the actor may need to upgrade after repeated error turns or discovery in specific namespaces without also upgrading the responder.
• Use actorTurnCallback when the user needs per-turn observability into generated code, raw runtime result, formatted output, or provider thoughts.
• Use agentStatusCallback when the user wants real-time task progress updates from the actor via await success(message) and await failed(message) calls.

Decision Guide

Map user intent to agent shape before writing code:

• "Use tools and answer" -> plain agent(...) with local functions, no recursion, no extra observability.
• "Inspect large context with code" -> add runtime, contextFields, and usually contextPolicy: { preset: 'checkpointed', budget: 'balanced' }.
• "Delegate focused semantic subtasks" -> use llmQuery(...); add mode: 'advanced' only when child tasks need their own runtime, tools, or discovery loop.
• "Need child agents with distinct responsibilities" -> use agents.local, and add fields.shared only when parent inputs truly need to flow into children.
• "Need tool discovery because names/schemas are not stable" -> use functions.discovery: true and generate discovery-first code.
• "Need a stronger actor only when the run gets noisy or large" -> use actorModelPolicy and keep the responder model separate.
• "Need debugging or traceability" -> start with debug: true or actorTurnCallback; do not add both unless the user clearly wants both prompt/runtime visibility and structured telemetry.
• "Need real-time progress updates" -> add agentStatusCallback so the actor can call await success(message) and await failed(message) to report sub-task progress.
• "Need certain errors to escape the agent loop" -> add bubbleErrors with an array of error classes; those errors propagate through function handlers, actor code, and llmQuery sub-agents all the way to .forward().

Choose options based on user needs, not feature completeness:

• Prefer mode: 'simple' unless recursive child agents materially improve the task.
• Prefer maxSubAgentCalls only when advanced recursion is enabled or the user needs explicit delegation limits.
• Prefer contextPolicy: { preset: 'checkpointed', budget: 'balanced' } by default, switch to adaptive when you want earlier summarization, use full for debugging, and reserve lean for real prompt pressure.

Mental Model

Treat AxAgent as a long-running JavaScript REPL that the actor steers over multiple turns, not as a fresh script generator on every turn.

• Successful code leaves variables, functions, imports, and computed values available in the runtime session.
• The actor should continue from existing runtime state instead of recreating prior work.
• actionLog, liveRuntimeState, and checkpoint summaries only control what the actor can see again in the prompt.
• Rebuild state only after an explicit runtime restart notice or when you intentionally need to overwrite a value.

Context Policy Presets

Use these meanings consistently when writing or explaining contextPolicy.preset:

• full: Keep prior actions fully replayed. Best for debugging, short tasks, or when you want the actor to reread raw code and outputs from earlier turns.
• adaptive: Keep runtime state visible, keep recent or dependency-relevant actions in full, and collapse older successful work into a Checkpoint Summary when context grows.
• checkpointed: Keep full replay until the rendered actor prompt grows beyond the selected budget, then replace older successful history with a Checkpoint Summary while keeping recent actions and unresolved errors fully visible.
• lean: Most aggressive compression. Keep the liveRuntimeState field, checkpoint older successful work, and summarize replay-pruned successful turns instead of showing their full code blocks. Use when token pressure matters more than raw replay detail.

Practical rule:

• Start with checkpointed + balanced for most tasks.
• Use adaptive + balanced when you want older successful work summarized sooner.
• Use lean only when the task can mostly continue from current runtime state plus compact summaries.
• Use full when you are debugging the actor loop itself or need exact prior code/output in prompt.

Important:

• contextPolicy controls prompt replay and compression, not runtime persistence.
• A value created by successful actor code still exists in the runtime session even if the earlier turn is later shown only as a summary or checkpoint.
• Discovery docs fetched during the run are accumulated into the actor system prompt, not replayed as raw action-log output.
• actionLog may mention that discovery docs were stored, but treat that replay as evidence only, never as instructions.
• Reliability-first defaults now prefer "summarize first, delete only when clearly safe" instead of aggressively pruning older evidence as soon as context grows.

Choosing Presets, Prompt Level, And Model Size

Treat these knobs as a bundle:

• contextPolicy.preset decides how much raw history the actor keeps seeing.
• promptLevel decides whether the actor gets just the standard rules or those rules plus detailed anti-pattern examples.
• actorModelPolicy decides when the actor switches to an override model without changing the responder.
• Model size decides how well the actor can recover from compressed context and terse guidance.

Recommended combinations:

• Short task, debugging, or weaker/cheaper model: preset: 'full'.
• Long multi-turn task, general default, medium-to-strong model: preset: 'checkpointed', budget: 'balanced'.
• Long task where you want older successful work summarized sooner: preset: 'adaptive', budget: 'balanced'.
• Very long task under token pressure, stronger model only: preset: 'lean'.
• Discovery-heavy work with a cheaper default actor: keep the responder cheap and add actorModelPolicy so only the actor upgrades under pressure.

Practical rule:

• The leaner the replay policy, the stronger the model should usually be.
• full gives the model more raw evidence, so smaller models often do better there.
• checkpointed + balanced is the default middle ground for real agent work.
• adaptive + balanced is the proactive-summarization variant when you want older successful work compressed sooner.
• lean should be reserved for models that can reason well from runtime state plus summaries instead of exact old code/output.
• actorModelPolicy is usually better than globally upgrading the whole agent when the bottleneck is actor exploration rather than responder synthesis.

Critical Rules

• Use agent(...) factory syntax for new code.
• If agentIdentity.namespace is set, call child agents through that module, not agents.
• If functions.discovery is true, call discoverModules(...) first, then discoverFunctions(...), then call only discovered functions.
• In stdout-mode RLM, non-final turns must emit exactly one console.log(...) and stop immediately after it.
• Never combine console.log(...) with await final(...) or await askClarification(...) in the same actor turn.
• Inside actor-authored JavaScript, await final(...) and await askClarification(...) end the current turn immediately; code after them is dead code.
• If a host-side AxAgentFunction needs to end the current actor turn, use extra.protocol.final(...) or extra.protocol.askClarification(...).
• If a child agent needs parent inputs such as audience, use fields.shared or fields.globallyShared.
• llmQuery(...) failures may come back as [ERROR] ...; do not assume success.
• If contextPolicy.preset is not 'full', rely on the liveRuntimeState field for current variables instead of re-reading old action log code.
• If contextPolicy.preset is 'adaptive', 'checkpointed', or 'lean', assume older successful turns may be replaced by a Checkpoint Summary and that replay-pruned successful turns may appear as compact summaries instead of full code blocks.
• In public forward() and streamingForward() flows, askClarification(...) does not go through the responder; it throws AxAgentClarificationError.
• When resuming after clarification, prefer error.getState() from the thrown AxAgentClarificationError, then call agent.setState(savedState) before the next forward(...).
• For offline tuning, hand off to the ax-agent-optimize skill and prefer eval-safe tools or in-memory mocks because agent.optimize(...) will replay tasks many times.
• Errors listed in bubbleErrors bypass all actor-loop catch blocks and propagate directly to the caller of .forward(). The same list is automatically inherited by recursive child agents created for advanced-mode llmQuery(...) calls.

Canonical Pattern

import { agent, ai, f } from '@ax-llm/ax';

const llm = ai({
  name: 'openai',
  apiKey: process.env.OPENAI_APIKEY!,
});

const assistant = agent(
  f()
    .input('query', f.string())
    .output('answer', f.string())
    .build(),
  {
    agentIdentity: {
      name: 'Assistant',
      description: 'Answers user questions',
    },
    contextFields: [],
  }
);

const result = await assistant.forward(llm, { query: 'What is TypeScript?' });
console.log(result.answer);

Child Agents And Module Namespace

Default child-agent module:

const writer = agent('draft:string -> revision:string', {
  agentIdentity: {
    name: 'Writer',
    description: 'Polishes drafts',
  },
  contextFields: [],
});

const coordinator = agent('query:string -> answer:string', {
  agents: { local: [writer] },
  contextFields: [],
});

Generated runtime call:

const result = await agents.writer({ draft: '...' });

Custom child-agent module:

const writer = agent('draft:string -> revision:string', {
  agentIdentity: {
    name: 'Writer',
    description: 'Polishes drafts',
  },
  contextFields: [],
});

const coordinator = agent('query:string -> answer:string', {
  agentIdentity: {
    name: 'Coordinator',
    description: 'Routes work',
    namespace: 'team',
  },
  agents: { local: [writer] },
  contextFields: [],
});

Generated runtime call:

const result = await team.writer({ draft: '...' });

Rules:

• Default child-agent module is agents.
• If agentIdentity.namespace is set, that becomes the child-agent module.
• Do not hardcode agents.<name>(...) when a custom namespace is configured.

Tool Functions And Namespaces

import { f, fn } from '@ax-llm/ax';

const tools = [
  fn('findSnippets')
    .description('Find handbook snippets by topic')
    .namespace('kb')
    .arg('topic', f.string('Topic keyword'))
    .returns(f.string('Matching snippet').array())
    .example({
      title: 'Find severity guidance',
      code: 'await kb.findSnippets({ topic: "severity" });',
    })
    .handler(async ({ topic }) => [])
    .build(),
];

const analyst = agent('query:string -> answer:string', {
  functions: {
    local: [
      {
        namespace: 'kb',
        title: 'Knowledge Base',
        selectionCriteria: 'Use for handbook and documentation lookups.',
        description: 'Handbook and documentation search helpers.',
        functions: tools.map(({ namespace: _namespace, ...tool }) => tool),
      },
    ],
  },
  contextFields: [],
});

Generated runtime call:

const snippets = await kb.findSnippets({ topic: 'severity' });

Rules:

• Prefer namespaced functions.
• Default function namespace is utils when no namespace is set.
• Use the runtime call shape await <namespace>.<name>({...}).

Host-Side Completion From Functions

Use this pattern when the actor should call a namespaced function, but the host-side function implementation should decide to end the turn:

import { f, fn } from '@ax-llm/ax';

const workflowTools = [
  fn('finishReply')
    .description('Complete the actor turn with the final reply text')
    .namespace('workflow')
    .arg('reply', f.string('Final reply text'))
    .returns(f.string('Final reply text'))
    .handler(async ({ reply }, extra) => {
      extra?.protocol?.final(reply);
      return reply;
    })
    .build(),
  fn('askForOrderId')
    .description('Complete the actor turn by requesting clarification')
    .namespace('workflow')
    .arg('question', f.string('Clarification question'))
    .returns(f.string('Clarification question'))
    .handler(async ({ question }, extra) => {
      extra?.protocol?.askClarification(question);
      return question;
    })
    .build(),
];

Rules:

• extra.protocol is only available when the function call comes from an active AxAgent actor runtime session.
• Use extra.protocol.final(...), extra.protocol.askClarification(...), or extra.protocol.guideAgent(...) only inside host-side function handlers.
• Inside actor-authored JavaScript, keep using the runtime globals final(...) and askClarification(...). final(message) and final(task, context) both go through the same responder-backed completion path; use the one-arg form when no extra context object is needed.
• extra.protocol.guideAgent(...) is handler-only internal control flow. It is not exposed as a JS runtime global or public completion type; it stops the current actor turn and appends trusted guidance to guidanceLog for the next iteration.
• askClarification(...) accepts either a simple string or a structured object with question plus optional UI hints such as type: 'date' | 'number' | 'single_choice' | 'multiple_choice' and choices.
• Do not model these protocol completions as normal registered tool functions or discovery entries.

Clarification And Resume State

Use this pattern when the actor should pause for user input and continue later from the same runtime state.

import {
  AxAgentClarificationError,
  AxJSRuntime,
  agent,
  ai,
} from '@ax-llm/ax';

const llm = ai({
  name: 'openai',
  apiKey: process.env.OPENAI_APIKEY!,
});

const tripAgent = agent('request:string, answer?:string -> reply:string', {
  contextFields: [],
  runtime: new AxJSRuntime(),
});

let savedState = tripAgent.getState();

try {
  await tripAgent.forward(llm, {
    request: 'Plan a Lisbon trip',
  });
} catch (error) {
  if (error instanceof AxAgentClarificationError) {
    console.log(error.question);
    savedState = error.getState();
  } else {
    throw error;
  }
}

if (savedState) {
  tripAgent.setState(savedState);
  const resumed = await tripAgent.forward(llm, {
    request: 'Plan a Lisbon trip',
    answer: 'June 1-5',
  });
  console.log(resumed.reply);
}

Public flow rules:

• forward() and streamingForward() throw AxAgentClarificationError when the actor calls askClarification(...).
• Successful final(...) completions always continue through the responder in those public flows.
• AxAgentClarificationError.question is the user-facing question text.
• AxAgentClarificationError.clarification is the normalized structured payload.
• AxAgentClarificationError.getState() returns the saved continuation state captured at throw time.
• agent.getState() and agent.setState(...) are the lower-level APIs for explicitly exporting or restoring continuation state on the agent instance.
• test(...) is different: it still returns structured completion payloads for harness/debug use instead of throwing clarification exceptions.

Structured clarification payloads:

• String shorthand is allowed: askClarification("What dates should I use?").
• Structured form is preferred for richer chat UIs:

askClarification({
  question: 'Which route should I use?',
  type: 'single_choice',
  choices: ['Fastest', 'Scenic'],
});

• Supported type values are text, number, date, single_choice, and multiple_choice.
• single_choice payloads with missing, empty, or malformed choices are downgraded to a plain clarification question instead of failing the turn.
• multiple_choice payloads must include at least two valid choices; otherwise the actor turn fails with a corrective runtime error that tells the model how to fix the call.
• Choice entries may be strings or { label, value? } objects.
• Invalid clarification payloads such as a missing question are still treated as actor-turn runtime errors, not as successful clarification completions.

What AxAgentState contains:

• version: serialized state schema version.
• runtimeBindings: the actual restorable JavaScript globals, limited to serializable values.
• runtimeEntries: inspect-style metadata for prompt rendering, including summary-only non-restorable values.
• actionLogEntries: prior actor turns that should still be replayed after resume.
• checkpointState: checkpoint summary text plus the covered turns when checkpointing was active.
• provenance: per-binding metadata for the last actor code that set that variable.

Practical notes:

• runtimeBindings restores execution state; runtimeEntries, actionLogEntries, and checkpointState restore prompt context.
• Resume does not create a fake rehydration action-log turn; provenance still points to the original actor code that set the value.
• When contextPolicy.preset is 'adaptive', 'checkpointed', or 'lean', resumed prompts include a Runtime Restore notice plus the liveRuntimeState field.
• When contextPolicy.preset is 'full', restore still happens, but the liveRuntimeState field is absent from the actor signature.
• Only serializable/structured-clone-friendly values are guaranteed to round-trip through getState() / setState(...).
• Reserved runtime globals such as inputs, tools, and protocol helpers are rebuilt fresh and are not part of saved state.
• Treat one agent instance as conversation-scoped when using setState(...); do not share one mutable resumed instance across unrelated concurrent conversations.

Bubble Errors

Use bubbleErrors when certain exceptions thrown inside function handlers or llmQuery sub-agent calls should propagate all the way out to the caller of .forward() instead of being caught by the actor loop and returned as [ERROR] strings.

import { agent, ai, f, fn } from '@ax-llm/ax';

class DatabaseError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'DatabaseError';
  }
}

class AuthError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'AuthError';
  }
}

const dbTool = fn('queryUsers')
  .description('Query the user database')
  .namespace('db')
  .arg('filter', f.string('Filter expression'))
  .returns(f.string('JSON result'))
  .handler(async ({ filter }) => {
    if (!isConnected()) throw new DatabaseError('DB connection refused');
    return JSON.stringify(await db.query(filter));
  })
  .build();

const myAgent = agent('query:string -> answer:string', {
  contextFields: [],
  functions: { local: [dbTool] },
  bubbleErrors: [DatabaseError, AuthError],
});

try {
  const result = await myAgent.forward(llm, { query: 'find active users' });
  console.log(result.answer);
} catch (err) {
  if (err instanceof DatabaseError) {
    console.error('DB is down:', err.message);
  } else if (err instanceof AuthError) {
    console.error('Auth failed:', err.message);
  } else {
    throw err;
  }
}

Rules:

• bubbleErrors takes an array of Error constructor classes (checked via instanceof).
• A matching error thrown anywhere — inside a function handler, during actor code execution, or inside a nested llmQuery(...) child agent — propagates immediately to .forward().
• The same bubbleErrors list is automatically propagated to recursive child agents created for advanced-mode llmQuery(...) calls.
• Use bubbleErrors for fatal infrastructure errors (DB down, auth failures, quota exceeded) that should abort the run entirely rather than let the actor retry.
• Do not use bubbleErrors for expected recoverable errors; let those return as [ERROR] ... strings so the actor can handle them.
• AxAgentClarificationError and AxAIServiceAbortedError always bubble up unconditionally — they do not need to be listed in bubbleErrors.

Unified Final Signal

There are two ways to end a successful run through the responder:

1. In actor JS code: Call final(message) when no extra context object is needed, or final(task, context) when you gathered evidence.
2. In function handlers: Use extra.protocol.final(...) with the same one-arg or two-arg forms.

import { agent, ai, f, fn } from '@ax-llm/ax';

const checkAccess = fn('checkAccess')
  .description('Verify access and complete if denied')
  .arg('resource', f.string('Resource name'))
  .returns(f.string('Access status'))
  .handler(async ({ resource }, extra) => {
    if (!hasAccess(resource)) {
      extra?.protocol?.final(`Access denied for ${resource}`);
    }
    return 'granted';
  })
  .build();

const result = await myAgent.forward(llm, { query });
console.log(result);

Rules:

• Use final(message) when the actor already knows the answer and no extra context object is needed.
• Use final(task, context) when context was gathered and needs synthesis into output fields.
• In function handlers, use extra.protocol.final(...) instead of a separate respond API.
• The responder still runs for both successful final(...) forms.
• Use askClarification(...) when the user must provide more information to continue.

Discovery Mode

Enable discovery mode when you want the actor to discover modules and fetch callable definitions on demand:

const analyst = agent('context:string, query:string -> answer:string', {
  agentIdentity: {
    name: 'Analyst',
    description: 'Analyzes long context',
    namespace: 'team',
  },
  contextFields: ['context'],
  agents: { local: [writer] },
  functions: {
    discovery: true,
    local: tools,
  },
});

Discovery APIs:

• await discoverModules(modules: string | string[])
• await discoverFunctions(functions: string | string[])

Both return Markdown.

• discoverModules(...) only lists modules that actually have callable entries.
• Grouped modules render in the Actor prompt as <namespace> - <selection criteria> when criteria is provided.
• If a requested module does not exist, discoverModules(...) returns a per-module markdown error without failing the whole call.
• discoverFunctions(...) may include argument comments from schema descriptions and fenced code examples from AxAgentFunction.examples.

Rules:

1. Call discoverModules(...).
2. If you need multiple modules, use one batched array call such as discoverModules(['timeRange', 'schedulingOrganizer']).
3. Log or inspect the returned markdown directly. Do not wrap it in JSON or custom objects.
4. If you need multiple callable definitions, prefer one batched discoverFunctions([...]) call.
5. Do not split discovery into separate calls with Promise.all(...).
6. Inspect the logged result.
7. Call discoverFunctions(...) for only the callables you plan to use.
8. Inspect the logged result.
9. Call discovered functions and child agents.
10. If a guessed call fails with TypeError, ... is not a function, or discovery Not found, stop guessing nearby names. Re-run discoverModules(...), then discoverFunctions(...), inspect the markdown again, and call only the exact discovered qualified name.
11. If tool docs or tool error messages specify an exact literal, type, or query format, reuse that exact documented value instead of synonyms or inferred aliases.

Examples:

const modules = await discoverModules(['team', 'kb', 'utils']);
console.log(modules);

const defs = await discoverFunctions(['team.writer', 'kb.findSnippets']);
console.log(defs);

Do not:

• Do not guess callable names when discovery mode is on.
• Do not guess alternate callable names after invalid callable errors.
• Do not assume sub-agents live under agents if agentIdentity.namespace is configured.
• Do not dump large pre-known tool definitions into actor code when discovery mode is enabled.
• Do not use Promise.all(...) to fan out discovery calls across modules or definitions.
• Do not convert discovery markdown into JSON before logging or using it.

RLM Actor Code Rules

Use these rules when generating actor JavaScript for RLM in stdout mode:

• Treat each actor turn as exactly one observable step.
• Inspect what already exists before recomputing it. If a prior turn successfully created a value, prefer reusing that runtime value.
• If you need to inspect a value, compute it or read it, console.log(...) it, and stop immediately after that console.log(...).
• On the next turn, continue from the existing runtime state and use the logged result from Action Log only as evidence for what happened.
• If the prompt contains Live Runtime State, treat it as the canonical view of current variables.
• Errors from child-agent or tool calls appear in Action Log; inspect them and fix the code on the next turn.
• Non-final turns should contain exactly one console.log(...).
• Final turns should call await final(outputGenerationTask, context) or await askClarification(...) without console.log(...).
• Do not write a complete multi-step program in one actor turn.
• Do not re-declare or recompute values just because older turns are summarized; only rebuild after an explicit runtime restart or when you intentionally want a new value.
• Do not assume older successful turns remain fully replayed; adaptive or lean policies may collapse them into a Checkpoint Summary block or compact action summaries.

Small reuse example:

Turn 1:

const customers = await kb.findCustomers({ segment: 'active' });
console.log(customers.length);

Turn 2:

const topCustomers = customers.slice(0, 3);
console.log(topCustomers);

Reason: turn 2 reuses customers from the persistent runtime. Live Runtime State or summaries may change how turn 1 is shown in the prompt, but they do not remove the value from the runtime session.

RLM Test Harness

Use agent.test(code, contextFieldValues?, options?) when the user wants to validate JavaScript snippets against the actual AxAgent runtime environment without running the full Actor/Responder loop.

import { AxJSRuntime, agent, f, fn } from '@ax-llm/ax';

const runtime = new AxJSRuntime();

const tools = [
  fn('sum')
    .description('Return the sum of the provided numeric values')
    .namespace('math')
    .arg('values', f.number('Value to add').array())
    .returns(f.number('Sum of all values'))
    .handler(async ({ values }) =>
      values.reduce((total, value) => total + value, 0)
    )
    .build(),
];

const harness = agent('query:string -> answer:string', {
  contextFields: ['query'],
  runtime,
  functions: { local: tools },
  contextPolicy: { preset: 'checkpointed', budget: 'balanced' },
});

const output = await harness.test(
  'console.log(await math.sum({ values: [3, 5, 8] }))',
  { query: 'sum the values' }
);

console.log(output);

Rules:

• test(...) creates a fresh runtime session per call.
• It exposes the same runtime globals the actor would see for configured contextFields: inputs, non-colliding top-level aliases, namespaced functions, child agents, and llmQuery.
• In AxJSRuntime, do not rely on calling inspect_runtime() from inside test(...) snippets yet; prefer checking runtime globals directly inside the snippet.
• It returns the formatted runtime output string.
• It throws on runtime failures instead of returning LLM-style error strings.
• Do not call final(...) or askClarification(...) inside test(...) snippets.
• Pass only contextFields values to test(...); it is not a general way to inject arbitrary non-context inputs.
• If the snippet uses llmQuery(...), provide an AI service through the agent config or options.ai.

RLM Adaptive Replay

Prefer this configuration for long, multi-turn runtime analysis:

const analyst = agent(
  'context:string, question:string -> answer:string, findings:string[]',
  {
    contextFields: ['context'],
    runtime: new AxJSRuntime(),
    maxTurns: 10,
    contextPolicy: {
      preset: 'adaptive',
      budget: 'balanced',
    },
  }
);

Rules:

• Use preset: 'full' when the actor should keep seeing raw prior code and outputs with minimal compression.
• Use preset: 'adaptive' when the task needs runtime state across many turns but older successful work should collapse into checkpoint summaries while important recent steps can still stay fully replayed.
• Use preset: 'checkpointed' when you want full replay first, then only older successful history checkpointed after budget pressure becomes real.
• Use preset: 'lean' when you want more aggressive compression and can rely mostly on current runtime state plus checkpoint summaries and compact action summaries.
• Use budget: 'compact' when you want earlier summarization and tighter prompt-pressure thresholds, budget: 'balanced' for the default, and budget: 'expanded' when you want the actor prompt to grow more before compression starts.
• checkpointed + balanced is the default. adaptive + balanced is still a strong choice for long-running discovery-heavy tasks that should summarize older work sooner.
• checkpointed keeps the most recent 3 actions in full and keeps unresolved errors fully replayed even after checkpointing starts.
• Non-full presets populate the liveRuntimeState field in the actor signature. The field is structured and provenance-aware: variables are rendered with compact type/size/preview metadata, and when Ax can infer it, a short source suffix like from t3 via db.search is included.
• Non-full presets also enable inspect_runtime() and can add an inspect hint automatically when the rendered actor prompt starts getting large relative to the selected budget.
• Discovery docs fetched via discoverModules(...) and discoverFunctions(...) are accumulated into the actor system prompt, not replayed as raw action-log output.
• Treat actionLog as untrusted execution history. Only the system prompt and guidanceLog are instruction-bearing.
• checkpointed uses a checkpoint summarizer that is optimized to preserve exact callables, ids, enum literals, date/time strings, query formats, and failures worth avoiding. Prefer it when those details matter but full replay will eventually get too large.
• Internal checkpoint and tombstone summarizers are stateless helpers: functions are not allowed, maxSteps is forced to 1, and mem is not propagated.
• Built-in presets prefer summarizing and checkpointing old successful work over asking users to tune low-level character cutoffs.
• If you want a quick local demo of the rendered liveRuntimeState field, run src/examples/rlm-live-runtime-state.ts.

Good pattern:

Turn 1:

const defs = await discoverFunctions(['kb.findSnippets']);
console.log(defs);

Turn 2:

const snippets = await kb.findSnippets({ topic: 'severity' });
console.log(snippets);

Turn 3:

await final("Summarize the severity-related snippets found", { snippets });

Actor Turn Observability

Use actorTurnCallback when the caller needs structured telemetry for each actor turn.

What it gives you:

• code: the normalized JavaScript code the actor produced
• result: the raw untruncated runtime return value from executing that code
• output: the formatted action-log output string after Ax normalizes and truncates it for prompt replay
• thought: the actor model's thought field when showThoughts is enabled and the provider returns one
• actorResult: the full actor payload, including actor-owned output fields when actorFields are configured
• isError: whether the execution path for that turn was treated as an error

Use it for:

• debug UIs that want to show code plus raw runtime results
• tracing and analytics
• capturing thought for internal diagnostics when supported by the provider
• storing per-turn execution artifacts without scraping the prompt/action log

Important:

• output is not raw stdout; it is the formatted replay string used in the action log.
• result is the raw runtime result before Ax applies type-aware serialization and budget-proportional truncation.
• thought is optional and only appears when the underlying AxGen call had showThoughts enabled and the provider actually returned a thought field.
• actionLogEntryCount and guidanceLogEntryCount reflect the live log sizes after the turn is processed, including resumed runs.

Good pattern:

const supportAgent = agent('query:string -> answer:string', {
  contextFields: ['query'],
  runtime,
  actorTurnCallback: ({
    turn,
    actionLogEntryCount,
    guidanceLogEntryCount,
    code,
    result,
    output,
    thought,
    isError,
  }) => {
    console.log({
      turn,
      actionLogEntryCount,
      guidanceLogEntryCount,
      isError,
      code,
      rawResult: result,
      replayOutput: output,
      thought,
    });
  },
  actorOptions: {
    model: 'gpt-5.4-mini',
    showThoughts: true,
  },
});

Agent Status Callback

Use agentStatusCallback when the caller wants real-time progress updates from the actor. When set, the actor can call await success(message) and await failed(message) in its JavaScript turns.

const supportAgent = agent('query:string -> answer:string', {
  contextFields: ['query'],
  runtime,
  agentStatusCallback: (message, status) => {
    console.log(`[${status}] ${message}`);
  },
});

Rules:

• agentStatusCallback receives (message: string, status: 'success' | 'failed').
• When set, the actor prompt automatically includes success(message) and failed(message) as available runtime functions.
• The actor is instructed to keep the user updated of task progress.
• success and failed are reserved runtime names when the callback is configured.
• Child agents inherit the callback via the rlm config.

Option Layout

Use these top-level controls consistently:

• mode: controls whether llmQuery(...) stays simple or delegates to recursive child agents in advanced mode
• recursionOptions.maxDepth: limits recursive llmQuery(...) depth
• maxSubAgentCalls: shared delegated-call budget across the whole run, including recursive children
• maxRuntimeChars: runtime/output truncation ceiling for console logs, tool results, and interpreter output replay. The actual limit is computed dynamically each turn based on remaining context budget (see Dynamic Output Truncation below)
• summarizerOptions: default model/options for the internal checkpoint summarizer
• actorOptions: actor-only forward options such as description, model, modelConfig, thinkingTokenBudget, and showThoughts
• actorModelPolicy: actor-only model override rules based on consecutive error turns or discovery fetches from listed namespaces
• responderOptions: responder-only forward options
• agentStatusCallback: real-time progress updates from actor via success(message) and failed(message)
• judgeOptions: built-in judge options for agent.optimize(...); for tuning workflows use the ax-agent-optimize skill
• bubbleErrors: error classes that propagate out of function handlers, actor code, and llmQuery sub-agents directly to .forward() instead of being caught and returned as [ERROR] strings

Canonical shape:

const researchAgent = agent('query:string -> answer:string', {
  contextFields: ['query'],
  runtime,
  mode: 'advanced',
  recursionOptions: {
    maxDepth: 2,
  },
  maxRuntimeChars: 3000,
  summarizerOptions: {
    model: 'gpt-5.4-mini',
    modelConfig: { temperature: 0.1, maxTokens: 180 },
  },
  contextPolicy: {
    preset: 'checkpointed',
    budget: 'balanced',
  },
  actorOptions: {
    description: 'Use tools first and keep JS steps small.',
    model: 'gpt-5.4-mini',
  },
  actorModelPolicy: [
    {
      model: 'gpt-5.4',
      aboveErrorTurns: 2,
      namespaces: ['db', 'kb'],
    },
  ],
  responderOptions: {
    model: 'gpt-5.4-mini',
  },
});

Semantics:

• mode stays top-level; there is no recursionOptions.mode.
• maxRuntimeChars sets the truncation ceiling and is separate from contextPolicy.budget. The effective limit per turn is computed dynamically (see below).
• summarizerOptions tunes only the internal checkpoint summarizer. It does not change actor or responder model selection.
• The current merged actor model stays the default base model. actorModelPolicy only overrides it when a rule matches.
• actorModelPolicy only switches the actor model. It does not change responderOptions.model.
• Recursive child agents can inherit actorModelPolicy; use a child override only when that child needs different routing behavior.
• actorModelPolicy entries are ordered from weaker to stronger. If multiple rules match, the last matching entry wins.
• If one entry also defines namespaces, any successful discoverFunctions(...) fetch from one of those namespaces marks the rule as matched starting on the next actor turn.

When choosing these options for a user:

• Do not add mode: 'advanced' just because recursion exists as a feature. Add it only when delegated children need their own tool/discovery/runtime loop.
• Do not add recursionOptions at all if the user does not need recursive delegation.
• Do not add judgeOptions in normal agent examples; reserve that for optimize/eval workflows.
• Keep actorOptions focused on actor-only forward concerns such as description, model, modelConfig, thinkingTokenBudget, and showThoughts.
• Use actorModelPolicy when the actor is the bottleneck and you want the responder to stay fixed.

Dynamic Output Truncation

Runtime output truncation is budget-proportional and type-aware:

Budget-proportional sizing: The effective truncation limit scales with remaining context budget. Early turns (empty action log) use the full maxRuntimeChars ceiling. As the action log fills toward targetPromptChars, the limit decays linearly down to 15% of the ceiling, hard-floored at 400 chars. This means early turns preserve more output detail while later turns conserve context for reasoning.

Type-aware serialization: Non-string runtime output is serialized with structural awareness before the char-budget truncation pass:

• Large arrays (>10 items): first 3 + last 2 items are kept; middle items replaced with ... [N hidden items].
• Deep objects (>3 levels): nested values beyond depth 3 replaced with [Object] or [Array(N)].
• Error stack traces: first 3 + last 1 stack frames kept; middle frames replaced with ... [N frames hidden].
• Simple values: standard JSON.stringify passthrough.

This means the actor sees structurally informative output even when the char budget is tight, rather than a blindly head-truncated string.

Users do not need to configure this behavior — it is automatic. maxRuntimeChars sets the upper bound; the dynamic system only ever reduces, never exceeds it.

Actor Prompt Controls

Use actorOptions for actor-only forward options and responderOptions for responder-only tuning.

Key fields:

• actorOptions.description: append extra actor-specific instructions without changing the responder prompt
• actorOptions.model / responderOptions.model: split model choice across actor and responder when needed
• actorModelPolicy: auto-switch only the actor when the run is on a consecutive error streak or discovery fetches land in specific namespaces

Good split-model pattern:

const researchAgent = agent('query:string -> answer:string', {
  contextFields: ['query'],
  runtime,
  contextPolicy: { preset: 'checkpointed', budget: 'balanced' },
  actorOptions: {
    model: 'gpt-5.4',
  },
  responderOptions: {
    model: 'gpt-5.4-mini',
  },
});

Model guidance:

• Put the stronger model on the actor when the task depends on multi-turn exploration, discovery, runtime state reuse, or compressed replay.
• Put the stronger model on the responder only when the hard part is final synthesis/formatting rather than exploration.
• For cost-sensitive setups, a common pattern is stronger actor + cheaper responder, not the other way around.
• Prefer actorModelPolicy over globally upgrading the whole agent when the actor only needs help after context grows or the run starts thrashing.
• Pair contextPolicy: { preset: 'checkpointed', budget: 'balanced' } with actorModelPolicy when you want full replay first and actor-only upgrades triggered by errors or discovered tool domains.

Invalid pattern:

const defs = await discoverFunctions(['kb.findSnippets']);
console.log(defs);
const snippets = await kb.findSnippets({ topic: 'severity' });
await final("Summarize severity findings", { snippets });

Reason: this mixes observation and follow-up work in one turn.

Shared Fields

If a child agent requires a parent field such as audience, prefer shared fields:

const writingCoach = agent(
  'draft:string, audience:string -> revision:string',
  {
    agentIdentity: {
      name: 'Writing Coach',
      description: 'Polishes summaries for a target audience',
    },
    contextFields: [],
  }
);

const analyst = agent(
  'context:string, audience:string, query:string -> answer:string',
  {
    agents: { local: [writingCoach] },
    fields: { shared: ['audience'] },
    contextFields: ['context'],
  }
);

Generated runtime call:

const polished = await agents.writingCoach({ draft: summary });

Rules:

• Use fields.shared for direct children.
• Use fields.globallyShared for all descendants.
• Do not manually thread a parent field on every child call when shared fields fit the use case.

Shared Agents And Shared Functions

Use grouped config:

const parent = agent('query:string -> answer:string', {
  agents: {
    local: [worker],
    shared: [logger],
    globallyShared: [auditor],
  },
  functions: {
    local: [searchTool],
    shared: [scoreTool],
    globallyShared: [traceTool],
  },
  contextFields: [],
});

Rules:

• agents.shared and functions.shared propagate one level down.
• agents.globallyShared and functions.globallyShared propagate to all descendants.
• Use excluded when a child should not receive a propagated field, agent, or function.

Tuning Hand-off

When the user wants agent.optimize(...), judge configuration, eval datasets, saved optimization artifacts, or recursive optimization guidance, use the ax-agent-optimize skill.

Keep this skill focused on building and running agents. For tuning work:

• use eval-safe tools or in-memory mocks
• treat judgeOptions as part of the optimize workflow
• choose a deterministic metric when scoring is objective; use the built-in judge only when run quality needs qualitative review
• keep runtime authoring guidance here and optimization guidance in ax-agent-optimize

llmQuery(...) Rules

Available forms:

• await llmQuery(query, context?)
• await llmQuery({ query, context? })
• await llmQuery([{ query, context }, ...])

Rules:

• llmQuery(...) forwards only the explicit context argument.
• Parent inputs are not automatically available to llmQuery(...) children.
• In mode: 'simple', llmQuery(...) is a direct semantic helper.
• In mode: 'advanced', llmQuery(...) delegates a focused subtask to a child AxAgent with its own runtime and action log while recursion depth remains.
• In advanced mode, no parent contextFields are auto-inserted into recursive children. Only explicit llmQuery(..., context) payload is available there.
• If context is a plain object, safe keys are exposed as child runtime globals and the full payload is also available as context.
• In advanced mode, use llmQuery(...) to offload discovery-heavy, tool-heavy, or multi-turn semantic branches so the parent action log stays smaller and more focused.
• In advanced mode, use batched llmQuery([...]) only for independent subtasks. Use serial calls when later work depends on earlier results.
• In advanced mode, a good pattern is: parent does coarse discovery and JS narrowing, child llmQuery(...) calls handle focused branch analysis, then parent merges child outputs and finishes.
• In advanced mode with functions.discovery: true, prefer putting noisy tool discovery, discoverFunctions(...), and branch-specific tool chatter inside delegated child calls when those branches are independent or semantically distinct.
• In advanced mode, pass compact named object context to children instead of huge raw parent payloads. This makes the delegated prompt easier to follow and gives the child useful top-level globals.
• In advanced mode, do not assume child-created variables, discovered docs, or action-log history come back to the parent. Only the child return value comes back.
• In advanced mode, if a child calls askClarification(...), that clarification bubbles up and ends the top-level run.
• In advanced mode, recursion is depth-limited: maxDepth: 0 makes top-level llmQuery(...) simple, maxDepth: 1 makes top-level llmQuery(...) advanced and child llmQuery(...) simple.
• In advanced mode, batched delegated children are cancelled when a sibling child asks for clarification or aborts, so use batched form only when those branches are truly independent.
• maxSubAgentCalls is a shared budget across the whole top-level run, including recursive children.
• Single-call llmQuery(...) may return [ERROR] ... on non-abort failures.
• Batched llmQuery([...]) returns per-item [ERROR] ....
• If a result starts with [ERROR], inspect or branch on it instead of assuming success.

Minimal example:

const summary = await llmQuery('Summarize this incident', inputs.context);
if (summary.startsWith('[ERROR]')) {
  console.log(summary);
} else {
  console.log(summary);
}

Advanced recursive discovery example:

const narrowedIncidents = incidents.map((incident) => ({
  id: incident.id,
  timeline: incident.timeline,
  notes: incident.notes.slice(0, 1200),
}));

const [severityReview, followupReview] = await llmQuery([
  {
    query:
      'Use discovery and available tools to review severity policy alignment. Return compact findings.',
    context: {
      incidents: narrowedIncidents,
      rubric: 'severity-policy',
    },
  },
  {
    query:
      'Use discovery and available tools to review postmortem and follow-up obligations. Return compact findings.',
    context: {
      incidents: narrowedIncidents,
      rubric: 'postmortem-followup',
    },
  },
]);

const merged = await llmQuery(
  'Merge these delegated reviews into one manager-ready summary with next steps.',
  {
    severityReview,
    followupReview,
    audience: inputs.audience,
  }
);

Delegation decision guide:

• JS-only — deterministic logic (filter, sort, count, regex, date math) → do it inline, don't delegate.
• Single-shot semantic — needs LLM reasoning but no tools or multi-step exploration → single llmQuery with narrow context.
• Full delegation — needs its own discovery, tool calls, or >2 turns of exploratory work → llmQuery as child agent.
• Parallel fan-out — 2+ independent subtasks each qualifying for delegation → batched llmQuery([...]).

Context handling:

• In advanced mode, the context object is injected into the child's JS runtime as named globals — it does NOT go into the child's LLM prompt. The child's prompt sees only a compact metadata summary (types, sizes, element keys) of the delegated context.
• The child actor explores the delegated context with code, the same way the parent explores inputs.*.
• Always narrow with JS before delegating — never pass raw inputs.*. Name context keys semantically (e.g. { emails: filtered, rubric: 'classify-urgency' }).
• Estimate total sub-agent calls before fanning out. maxSubAgentCalls is a shared budget across all recursion levels.

Divide-and-conquer patterns:

• Fan-Out / Fan-In: JS narrows into categories → llmQuery([...]) fans out per category → JS or one more llmQuery merges results.
• Pipeline: serial llmQuery calls where each depends on the prior result.
• Scout-then-Execute: first child explores (e.g. check availability) → parent processes with JS → second child acts (e.g. draft invite).

Notes:

• Use these patterns when one task naturally splits into focused semantic branches with their own discovery or tool usage.
• Keep the parent responsible for orchestration, cheap JS narrowing, and final assembly.
• See src/examples/rlm-discovery.ts for the full recursive discovery demo.

Short API Reference

agentIdentity

agentIdentity?: {
  name: string;
  description: string;
  namespace?: string;
}

• name is normalized to camelCase for child-agent function names.
• namespace changes the child-agent module from default agents to a custom module such as team.

AxAgentOptions

{
  contextFields: readonly (string | { field: string; promptMaxChars?: number })[];

  agents?: {
    local?: AxAnyAgentic[];
    shared?: AxAnyAgentic[];
    globallyShared?: AxAnyAgentic[];
    excluded?: string[];
  };

  fields?: {
    local?: string[];
    shared?: string[];
    globallyShared?: string[];
    excluded?: string[];
  };

  functions?: {
    local?: AxFunction[];
    shared?: AxFunction[];
    globallyShared?: AxFunction[];
    excluded?: string[];
    discovery?: boolean;
  };

  runtime?: AxCodeRuntime;
  promptLevel?: 'default' | 'detailed';
  maxSubAgentCalls?: number;
  maxBatchedLlmQueryConcurrency?: number;
  maxTurns?: number;
  maxRuntimeChars?: number;
  contextPolicy?: AxContextPolicyConfig;
  summarizerOptions?: Omit<AxProgramForwardOptions<string>, 'functions'>;
  actorFields?: string[];
  actorTurnCallback?: (turn: {
    turn: number;
    actionLogEntryCount: number;
    guidanceLogEntryCount: number;
    actorResult: Record<string, unknown>;
    code: string;
    result: unknown;
    output: string;
    isError: boolean;
    thought?: string;
  }) => void | Promise<void>;
  inputUpdateCallback?: (currentInputs: Record<string, unknown>) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined;
  mode?: 'simple' | 'advanced';
  actorModelPolicy?: readonly [
    | {
        model: string;
        aboveErrorTurns: number;
        namespaces?: string[];
      }
    | {
        model: string;
        aboveErrorTurns?: number;
        namespaces: string[];
      },
    ...Array<
      | {
          model: string;
          aboveErrorTurns: number;
          namespaces?: string[];
        }
      | {
          model: string;
          aboveErrorTurns?: number;
          namespaces: string[];
        }
    >,
  ];
  recursionOptions?: Partial<Omit<AxProgramForwardOptions, 'functions'>> & {
    maxDepth?: number;
  };
  actorOptions?: Partial<AxProgramForwardOptions & { description?: string }>;
  responderOptions?: Partial<AxProgramForwardOptions & { description?: string }>;
  judgeOptions?: Partial<AxJudgeOptions>;
  bubbleErrors?: ReadonlyArray<new (...args: any[]) => Error>;
}

• actorTurnCallback fires for the root agent and for recursive child agents that run actor turns.
• actorModelPolicy applies to the actor loop and can be inherited by recursive child agents unless you override it there.
• namespaces matches exact discovery namespaces from successful discoverFunctions(...) lookups and starts affecting model choice on the next actor turn.
• Consecutive error turns reset after a successful non-error turn and when checkpoint summarization refreshes to a new fingerprint.
• maxSubAgentCalls is a shared delegated-call budget across the entire run.

Observability: getChatLog() and getUsage()

AxAgent exposes two sub-programs (Actor and Responder). Both getChatLog() and getUsage() return an object split by role — unlike AxGen, which returns a flat array.

getChatLog()

Returns the full normalized chat history split by actor/responder after any .forward() call. Each entry is one ai.chat() round-trip. The actor accumulates one entry per turn; the responder typically has one.

const log = myAgent.getChatLog();
// { actor: AxChatLogEntry[], responder: AxChatLogEntry[] }

for (const entry of log.actor) {
  console.log('Actor model:', entry.model);
  for (const msg of entry.messages) {
    console.log(`[${msg.role}]`, msg.content);
  }
}

for (const entry of log.responder) {
  console.log('Responder model:', entry.model);
  for (const msg of entry.messages) {
    console.log(`[${msg.role}]`, msg.content);
  }
}

Each AxChatLogEntry captures the full prompt sent to the model and its response:

type AxChatLogMessage =
  | { role: 'system'; content: string }       // system prompt (includes <tools> block when functions present)
  | { role: 'user'; content: string }
  | { role: 'assistant'; content: string }    // may contain <think>...</think> and <tool_call>{...}</tool_call>
  | { role: 'tool'; name: string; content: string };

type AxChatLogEntry = {
  model: string;
  messages: AxChatLogMessage[];
  modelUsage?: AxProgramUsage;
};

getUsage()

Returns token usage split by actor/responder. Each sub-array contains one AxProgramUsage entry per model/run, merged by (ai, model) key.

const usage = myAgent.getUsage();
// { actor: AxProgramUsage[], responder: AxProgramUsage[] }

console.log('Actor tokens:', usage.actor[0]?.tokens);
console.log('Responder tokens:', usage.responder[0]?.tokens);

resetUsage()

Resets both actor and responder usage at once:

myAgent.resetUsage();

Type signatures

// AxAgent
agent.getChatLog(): { actor: readonly AxChatLogEntry[]; responder: readonly AxChatLogEntry[] }
agent.getUsage():   { actor: AxProgramUsage[]; responder: AxProgramUsage[] }
agent.resetUsage(): void

// AxGen (flat — no split)
gen.getChatLog(): readonly AxChatLogEntry[]
gen.getUsage():   AxProgramUsage[]

Examples

Fetch these for full working code:

• Agent — basic agent
• Functions — function validation
• Food Search — API tools
• Smart Home — state management
• RLM — RLM basic
• RLM Long Task — RLM context policy
• RLM Discovery — advanced recursive llmQuery plus discovery-heavy delegated subtasks
• RLM Shared Fields — shared fields
• RLM Adaptive Replay — adaptive replay
• RLM Live Runtime State — structured runtime-state rendering
• RLM Clarification Resume — clarification exception plus getState() / setState(...)
• Customer Support — classification agent
• Abort Patterns — abort handling

Do Not Generate

• Do not use new AxAgent(...) for new code unless explicitly required.
• Do not assume child agents are always under agents.*.
• Do not guess function names in discovery mode.
• Do not write a full multi-step RLM actor program in one turn.
• Do not combine console.log(...) with final(...).
• Do not forget fields.shared when child agents depend on parent inputs.
• Do not add bubbleErrors for ordinary recoverable tool errors; those should stay as [ERROR] strings so the actor can handle them.