AxAgent Optimize Codegen Rules (@ax-llm/ax)

AxAgent Optimize Codegen Rules (@ax-llm/ax)

Use this skill for agent.optimize(...) workflows. Prefer short, modern, copyable patterns. Do not repeat general agent-authoring guidance unless the user needs it. For generic ax(...) or flow(...) tuning with top-level optimize(...), use the ax-gepa skill instead.

Your job is to help the model choose a good optimization setup for the user's actual goal:

• If the user wants better tool use, prefer action-aware tasks and either a deterministic metric or the built-in judge depending on how objective the scoring is.
• If the user wants better wording only, responder optimization may be enough.
• If the user wants reusable improvements, include artifact save/load.
• If the user wants cost, tool-use, or child-agent delegation behavior improved, make the eval tasks expose those tradeoffs explicitly.

Use These Defaults

• Use agent.optimize(...) only after the agent is already configured and runnable.
• Prefer the built-in judge path first for normal agent tuning. Most users should start with tasks that include input and criteria, then let agent.optimize(...) use its default actor target and judge-based metric.
• Keep top-level optimize(program, train, metric, options) for non-agent generators and flows; do not rewrite normal agent task-record examples to the generic helper.
• Prefer a deterministic custom metric only when success is easy to score from the prediction and task record.
• Add judgeAI plus judgeOptions when the judge should run on a stronger or separate model than the agent runtime model.
• Only reach for a plain typed AxGen evaluator when the user needs LLM-as-judge behavior outside the built-in agent.optimize(...) flow.
• Default optimize target is the actor path; do not surface target unless the user clearly wants responder-only tuning or explicit program IDs.
• Use eval-safe tools or in-memory mocks because optimization replays tasks many times.
• Prefer precise tool return schemas such as f.object(...) over vague f.json(...) whenever the agent must reason about returned fields.
• Prefer task wording with canonical entity names like "the Atlas project" instead of ambiguous labels like "Atlas" when ambiguity could trigger pointless clarification.
• Save artifacts with axSerializeOptimizedProgram(result.optimizedProgram!), then restore with axDeserializeOptimizedProgram(saved) and agent.applyOptimization(...).
• For browser-safe persistence, let the caller store the serialized JSON anywhere they want such as localStorage, IndexedDB, or a backend.
• If bootstrap is enabled, bootstrapped demos are persisted inside result.optimizedProgram.demos; raw failed traces are not saved in v1.
• Auto-promoted context fields (large undeclared inputs kept runtime-only by autoUpgrade) appear in captured traces/demos as their truncated preview string, not the full value — same as declared truncate-style contextFields. This is expected; do not treat the shortened value as a bug in the saved demos.
• For first examples, pass a plain task array instead of splitting into train and validation unless the user already has a holdout set.
• GEPA-backed agent.optimize(...) now optimizes generic components exposed by the selected target programs; target: 'actor' only tunes actor components, target: 'responder' only tunes responder components, and target: 'all' broadens the component set.
• result.optimizedProgram.componentMap is the canonical saved artifact for agent GEPA runs. It may include actor instructions, descriptions, tool descriptions/names, templates, or runtime primitives depending on what the selected target exposes.
• When child-agent delegation matters, expose the child agents as named functions and tune against realistic call/no-call tasks.

Decision Guide

Pick the optimization shape from the user's need:

• "Make the agent use tools correctly" -> keep the default actor target and use expectedActions and forbiddenActions.
• "Make final answers read better" -> consider target: 'responder', but only if the task is not mostly tool-selection or clarification behavior.
• "Make the whole agent better" -> use the default actor target first; only broaden target selection when the user clearly wants that extra scope.
• "Tune child-agent delegation" -> use tasks that exercise when to call the child agent, when to call normal tools, and when to answer directly.