Self-optimizing prompts

A prompt baked into your deploy artifact can only improve on redeploy. This pattern moves the system prompt (and tool/skill definitions) into Mubit as versioned server-side resources: agents fetch the active version at call time, outcomes accrue against it, and the optimizer proposes better candidates from that evidence — reviewed, activated, and rolled back without touching agent code. Use it when your agents already record outcomes and prompt tuning has become a recurring manual chore.

How it works

set_prompt(v1) ──► agents get_prompt() per call ──► outcomes accrue
                                                        │
   activate ◄── review diff ◄── optimize_prompt() ◄─────┘
      │
      └─► (regression? → rollback to the retired version)

Every set_prompt creates a new PromptVersion (active, candidate, retired, or archived); activation is atomic and the displaced version stays addressable for rollback. optimize_prompt reads the agent's accumulated lessons and outcomes — the same signal the learning loop runs on — and produces a candidate version plus an optimization_summary and confidence. It never activates by default; you diff, then promote. Skills get the identical lifecycle with optimize_skill and the skill-version calls.

Serving the active prompt

The helper layer resolves the agent from the ambient session context and returns the content string directly:

import mubit
 
mubit.init(api_key=API_KEY, agent_id="ari")
 
prompt = mubit.get_prompt()                      # active version; cached for 60s
tools = mubit.get_skills(format="anthropic")     # skill defs as tool schemas
# formats: "openai" (default), "anthropic", "gemini", "raw"
 
mubit.set_prompt("You are Ari, Nimbus's support agent...", activate=True)
# set_prompt busts the local cache so the next get_prompt() sees the new version

Because agents fetch the prompt per call (cache notwithstanding), an activation propagates to the whole fleet within seconds — no redeploy.

Version lifecycle calls

optimize_prompt is top-level in all three SDKs (a typed helper from SDK v0.12.0 in Python/JS — client.optimize_prompt(agent_id=..., auto_activate=False, project_id=...) / client.optimizePrompt({...}) — and typed in Rust since 0.11); the surrounding version management lives on the raw surface:

The compact loop, from Nimbus's nightly cron:

resp = client.optimize_prompt(agent_id="ari", project_id=PROJECT, auto_activate=False)
if resp["confidence"] >= 0.6:
    active = client.advanced.get_prompt(agent_id="ari")
    diff = client.advanced.get_prompt_diff(
        agent_id="ari",
        version_a_id=active["version"]["version_id"],
        version_b_id=resp["candidate"]["version_id"],
    )
    post_for_review(resp["optimization_summary"], diff["diff_text"])
    # a human approves → client.advanced.activate_prompt_version(
    #     agent_id="ari", version_id=resp["candidate"]["version_id"])

The candidate's material is the rationales and directive_hints from your recorded outcomes — the better your attribution hygiene, the better the candidates. The full runnable workflow — including the console equivalents, shadow testing, and rollback — is Prompt optimization.

Champion/challenger, hands-off

Instances can run the comparison for you. With prompt shadow serving enabled, while a candidate exists get_prompt alternates deterministically between the champion and the challenger on a time bucket, so the challenger accrues real outcome statistics with no client-side changes. The champion/challenger evaluator then surfaces the winner — and when auto-promotion is enabled, an activated challenger is watched against the displaced champion's baseline score and automatically rolled back if post-promotion outcomes regress. Treat this as an instance feature to opt into once manual review has built trust in the loop, not as a starting point.

When not to use it

• Externally change-controlled prompts — if the prompt text is reviewed, signed off, and audited outside your systems, it must not drift by optimization. Pin it in your artifact (or keep versions in Mubit but never grant optimize_prompt a path to activation).
• Too little signal — the optimizer can synthesize a confident-looking candidate from a handful of outcomes. Wait for a meaningful sample with some genuine failures before acting on candidates.
• Prompts that encode hard invariants — safety-critical constraints belong in rule entries or code-level checks (Guardrails from failures), not in text an optimizer is allowed to rewrite.

Related

• Prompt optimization — the full runnable lifecycle, with console equivalents
• The outcome attribution loop — the signal the optimizer feeds on
• Reflection to lessons — the lessons folded into candidates
• Projects, agents, and skills — the resource model behind prompt and skill versions
• Control HTTP reference — the prompt lifecycle endpoints on the wire