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

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.