Skip to main content

Agent Spec Migration

The Agent Spec Migration screen lets you review and apply the Agent Compiler's version-2 recompile for every eligible agent in your tenant - one agent at a time, with your explicit approval before anything goes live.

Overview​

When Outermind releases a new version of the Agent Compiler, existing agents keep running on their original instructions until you choose to migrate them. The migration tool:

  1. Dry-runs the migration - Backfills a version-1 snapshot from each agent's current prose, recompiles it to a version-2 candidate, and shows you a line-level diff.
  2. Puts you in control - Nothing is promoted automatically. Each agent has its own Promote button; you decide which agents get the new version and when.
  3. Signals equivalence - A "no-op diff" badge means the recompiled prose is behaviourally equivalent to what the agent runs today. A large or surprising diff is a signal to fix the spec, not to push through.

Accessing the Screen​

Go to Workforce > Agents > Spec Migration. The screen requires the agents:write permission.

Running a Dry-Run​

  1. Click Run dry-run in the top-right corner.
  2. Wait while the system backfills and recompiles each eligible agent. This performs a real compile per agent and may take a moment.
  3. A summary bar appears once the run completes, showing total agents processed, how many succeeded, how many failed, and how many produced no-op diffs.

Reading the Results​

Each agent appears as a card:

ElementMeaning
Agent IDThe unique identifier for the agent.
Version badgeThe candidate version number and compile status (e.g. v2 - success).
No-op diff (green)The recompiled prose is behaviourally equivalent - safe to promote.
Unified diff (red/green lines)Lines removed from the current prose (red -) and lines added by the recompile (green +). Review carefully before promoting.
Warning bannerThe candidate did not compile cleanly. Fix the agent spec before promoting.
Error cardThe dry-run failed for this agent. The failing stage and error code are shown.

Promoting an Agent​

When you are satisfied with the diff for an agent:

  1. Click Promote on that agent's card.
  2. The candidate version goes live for this tenant immediately.
  3. The card shows a green Promoted badge confirming the change.

Only successfully compiled candidates can be promoted. Agents that produced an error or a failed compile status are not eligible until the underlying spec issue is resolved.

FAQ​

Does running the dry-run change anything? No. The dry-run only reads and recompiles - it does not modify agent instructions or any live data. Only the Promote action makes a change.

What does "no-op diff" mean? It means the Agent Compiler produced identical prose to what the agent currently runs on. This is the expected outcome for a well-formed spec. You can promote with confidence.

Can I promote all agents at once? Not from this screen - promotion is intentionally per-agent to give you full control. If you see unexpected diffs, you can choose to promote only the agents whose diffs look clean.

What if the dry-run fails for some agents? Agents that fail the dry-run display the error stage and code. The failure does not affect agents that succeeded. Investigate the failing agent's spec and re-run the dry-run after fixing it.

Do I need to run the dry-run again after promoting some agents? No. Already-promoted agents will show a Promoted badge for the rest of the session. You can promote remaining agents from the current results without re-running.