Ax Agent Rlm

AxAgent RLM Runtime Rules (@ax-llm/ax)

Use this skill for code-runtime agents and llmQuery(...) semantic-helper behavior. For ordinary agent setup, child agents, tool namespaces, clarification, and bubbleErrors, use ax-agent. For callbacks and logs, use ax-agent-observability. For memories and skill loading, use ax-agent-memory-skills.

Use These Defaults

• Use agent(...), not new AxAgent(...).
• In stdout-mode RLM, use one observable console.log(...) step per non-final actor turn.
• Rely on autoUpgrade (ON by default) for oversized inputs you did not declare in contextFields: any input value over ~8k serialized chars is kept runtime-only automatically, with a 1,200-char prompt preview plus a contextMetadata line, while the full value stays live in the runtime as inputs.<field>. Declare a field in contextFields only when you want a specific inline policy (promptMaxChars / keepInPromptChars) or need a large required non-string field kept out of the prompt (those are left inline by auto-upgrade).
• 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.
• Use contextMap for recurring long-context corpora when the distiller should start future runs with a small persisted orientation cache.
• Prefer promptLevel: 'default' for normal use.
• Use promptLevel: 'detailed' when you want extra anti-pattern examples and tighter teaching scaffolding in the actor prompt.
• Prefer executorModelPolicy when the actor may need to upgrade after repeated error turns or discovery in specific namespaces without also upgrading the responder.
• Use explicit child agents in functions: [...] when the task needs specialist agents with their own tools/runtime.
• Use llmQuery(...) only for focused semantic questions over narrowed context; it does not spawn a tool-using child AxAgent.
• Prefer maxSubAgentCalls only when you need an explicit cap on llmQuery(...) sub-query usage.

Mental Model

AxAgent is a three-stage pipeline. Each forward() call walks the stages in order:

distiller (RLM actor) -> executor (RLM actor) -> responder (synthesizer)

• distiller always runs first. It sees all original inputs so it can understand and normalize the task; declared contextFields stay runtime-only when present. It distils relevant evidence by writing runtime-language code in a multi-turn loop, then calls the runtime-exposed final(request, evidence) primitive. The request becomes the executor's inputs.executorRequest; it must be self-contained and restate the concrete action, target, and constraints, not vague wording like "do it". The distiller should expand the original user task with facts found in context, including follow-ups like "yes, do it". When no contextFields are configured, it still performs request normalization over the original inputs with contextFields: []. The distiller has no tools and is not a capability gate.
• executor runs unless the distiller skipped it (below). It receives non-context inputs plus inputs.executorRequest, a compact distilledContextSummary prompt field, and the real evidence live as inputs.distilledContext from the distiller's final(request, evidence) payload. Declared or auto-promoted context fields stay runtime-readable as inputs.<field> when contextMetadata lists them, but their raw contents are not pasted into the executor prompt. The executor owns tool use, decides whether to call its available functions or finish directly from distilled evidence, and reports actual tool results or failures.
• responder always runs last. It synthesizes the user's output signature from whichever upstream actor finished the run and must not contradict tool evidence gathered upstream.

Direct respond (executor skip)

With directResponse: 'auto' (the default), the distiller can end the run with the respond(task, evidence) primitive when the task needs no executor authority — the executor stage is skipped entirely (zero executor model calls) and the responder synthesizes straight from the distiller's evidence. Unlike final, whose evidence stays live in the shared session by reference, respond's evidence crosses into the responder prompt (budgeted by maxEvidenceChars), and the distiller's runtime variables are exported as the cross-run state exactly as the executor's would have been.

• Static agents (no functions, child agents, or native MCP/UCP operations) run respond-only: final is not offered to the distiller and every run is distiller → responder.
• Agents with executor authority from functions, child agents, or native MCP/UCP operations get respond alongside final under a conservative covenant: only for tasks answered purely by reading/synthesizing provided context, never when a listed function/module domain covers the need, never for current/live/fresh-state asks (context may be stale — tools are the source of truth for "now"), never for side effects. Landing-gate eval (both pinned models, 3 repeats): 0 false skips on tool-required tasks including a stale-context trap, 100% skip recall on pure context Q&A.
• directResponse: 'off' removes the primitive from the prompt and the runtime, and the pipeline rejects a respond payload outright.

Treat both actor stages as long-running code runtime sessions that the actor steers over multiple turns, not as fresh script generators on every turn. AxJSRuntime is the default; custom runtimes set language so the actor code field becomes <language>Code such as pythonCode while JavaScript keeps the legacy javascriptCode.

• 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.

RLM Actor Code Rules

Use these rules when generating actor JavaScript for RLM in AxJSRuntime stdout mode. For custom runtimes, follow the runtime's getUsageInstructions(), primitive overrides, and callable formatter instead.

• 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 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.
• 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/checkpointed/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.

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 character-based prompt 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 via discover(...) 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.
• Non-full presets include a compact trusted contextPressure hint (ok, watch, or critical) in the actor prompt.
• Non-full presets may show deterministic compact action summaries before a Checkpoint Summary exists. Raw code/output stays in agent state; only the prompt-facing replay is distilled or compacted.
• Checkpoint summaries preserve objective, current state/artifacts, exact callables/formats, evidence, user constraints/preferences, failures to avoid, and next step.

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.
• executorModelPolicy 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 high character-based prompt pressure, stronger model only: preset: 'lean'.
• Discovery-heavy work with a cheaper default actor: keep the responder cheap and add executorModelPolicy 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.
• executorModelPolicy is usually better than globally upgrading the whole agent when the bottleneck is actor exploration rather than responder synthesis.

Option Layout

Use these top-level controls consistently:

• recursionOptions.ai: routes llmQuery(...) sub-query calls to a different AI service than the parent run.
• recursionOptions.model, modelConfig, and other forward options: tune the AxGen call used by llmQuery(...).
• maxSubAgentCalls: shared llmQuery(...) sub-query budget across the whole run. Default is 100.
• maxBatchedLlmQueryConcurrency: caps batched llmQuery([...]) concurrency.
• maxRuntimeChars: runtime/output truncation ceiling for console logs, tool results, and interpreter output replay. The effective limit is computed dynamically each turn based on remaining context budget.
• summarizerOptions: default model/options for the internal checkpoint summarizer.
• contextPolicy: replay/checkpointing/compression policy.
• contextMap: optional persistent orientation cache injected into the distiller and updated once after each successful run. AxAgentContextMap evolves indefinitely by default; use { infiniteEvolve: false, evolveSteps: N } on the map object for finite warmup followed by reuse.
• contextOptions: distiller-stage forward options.
• autoUpgrade: smart defaults, ON by default. Auto-enables functionDiscovery for large tool catalogs and keeps oversized undeclared input values runtime-only with a truncated prompt preview. Set false to opt out, or tune per side: { functionDiscovery?: boolean | { aboveFunctionDocChars }, contextFields?: boolean | { promoteAboveChars, previewChars } }. Explicit functionDiscovery and declared contextFields always win.
• executorOptions: executor-stage forward options such as description, model, modelConfig, thinkingTokenBudget, and showThoughts.
• executorModelPolicy: executor-only model override rules based on consecutive error turns or discovery fetches from listed namespaces.
• responderOptions: responder-stage forward options.
• judgeOptions: built-in judge options for agent.optimize(...); for tuning workflows use ax-agent-optimize.

Canonical shape:

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

Semantics:

• maxRuntimeChars sets the truncation ceiling and is separate from contextPolicy.budget.
• summarizerOptions tunes only the internal checkpoint summarizer. It does not change actor or responder model selection.
• executorModelPolicy only switches the actor model. It does not change responderOptions.model.
• llmQuery(...) uses recursionOptions.ai when set, otherwise it falls back to the parent .forward(ai, ...) service.
• recursionOptions configures the AxGen semantic sub-query used by llmQuery(...); it does not create a child AxAgent and cannot give the sub-query tools.
• executorModelPolicy entries are ordered from weaker to stronger. If multiple rules match, the last matching entry wins.
• If one entry defines namespaces, any successful discover(...) function-definition fetch from one of those namespaces marks the rule as matched starting on the next actor turn.
• Do not add recursionOptions unless the user needs different model/options for llmQuery(...).

Dynamic Output Truncation

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

• Early turns with little action-log pressure 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.
• Large arrays keep the first 3 and last 2 items, with the middle replaced by ... [N hidden items].
• Deep objects replace nested values beyond depth 3 with [Object] or [Array(N)].
• Error stack traces keep the first 3 and last 1 stack frames.
• Simple values use standard JSON.stringify passthrough.

Users do not need to configure this behavior. maxRuntimeChars sets the upper bound; the dynamic system only reduces it.