How to Change an Agent System Without Breaking Live Work

Most agent designs talk about creation. Real systems spend much of their life changing.

You add a specialist. You move a public route. You split one overloaded role into two. You change the model profile. You discover that an old instruction caused a recurring failure. You replace a project layout that no longer fits the work.

Those are not just edits. Once real requests, persistent contexts, and delivery obligations exist, they are migration problems. A Practical Architecture for Reliable Multi-Agent Systems explains the boundaries a live change must preserve.

The goal is not to freeze the system. It is to let it improve without creating two owners for the same work, stranding old requests, or treating a source file as proof that the new design is live.

The detailed proof vocabulary lives in The Proof Ladder for AI Systems.

Source changes and live changes are different events

Suppose you add a new role definition and a better bootstrap prompt to source control. That is a useful change. It does not prove that a new endpoint exists, that it has the intended project context, that callers can reach it, or that it returns useful work.

I separate the change into two truths:

The gap between them is where many false claims start. A system can be source-ready without being active. It can be active without being routing-proven. It can route requests correctly without producing a useful result for a real consumer.

Naming each state makes a change easier to discuss honestly. It also tells an operator what to check next.

Build new roles inactively first

When a role needs to change substantially, I prefer a fresh endpoint generation over quietly rewriting a live task’s identity.

The sequence is practical:

1. Define the updated charter, interface, model profile, bootstrap, and rebuild steps in source control.
2. Create the replacement in the intended project and working context.
3. Read back its live identity and configuration rather than inferring them from the setup prompt.
4. Add it to the live registry in an inactive state.
5. Validate the route and return behavior before admitting normal traffic.
6. Keep the old path available until representative work proves the replacement.

Inactive registration is useful because it separates creation from activation. You can inspect whether the task has the right project, instructions, model, and interface before a normal requester depends on it.

The clean replacement also avoids carrying along old chat history, uncertain working state, and half-finished obligations. A new generation should begin from the current source definition. Existing work should finish, recover, or close through the route that still owns it.

Building One Agent from Coordinated Roles in Codex covers the creation and read-back steps in more detail.

Two public routes must not create two cases

An old public route and a new one may need to coexist during a migration. That is often safer than abruptly redirecting every caller.

But the two routes create a subtle duplicate risk. A requester may retry. An old automation may still call the previous address. A fallback may run after the preferred route has already admitted the request. If each route creates its own independent owner work, the system can produce two answers or two side effects for one semantic request.

The answer is to let different transport requests converge on one owner-scoped identity.

old public route + transport key A
new public route + transport key B
             -> same semantic owner key
             -> one owner case and one integrated result

The transport keys can differ because the routes are different. The semantic key should be stable because the underlying work is the same. The owner can then decide whether a similar request deserves a new case; the transport layer only prevents mechanical duplication.

This pattern is more useful than a big-bang cutover. It gives you a fallback without turning the fallback into a second decision-maker.

Apply proof to the migration

The question is not, “Did the migration work?” It is, “Which migration claim did this test support?”

First prove that the new route reaches the intended owner and that old and new entry points converge instead of duplicating work. Then prove that owner returns and requester delivery work. Only representative product work can show that the replacement is useful in normal conditions.

The Proof Ladder for AI Systems owns those evidence rungs. Here, the application is simple: do not retire the predecessor until the new path has earned the relevant proof.

Let failure shape the next version

The most useful changes often come from a failure that exposed a confused responsibility.

Perhaps the public entry point was also trying to reason about the domain and wait for callbacks. The fix may be to move semantic judgment to a domain owner and let the public role handle admission and return.

Perhaps a worker completed but nobody received the result. The fix may be an explicit callback and delivery receipt, not a better worker prompt.

Perhaps a retry created duplicate work. The fix may be an owner-scoped identity shared by the old and new routes, not more retries.

Perhaps a learning closeout repeatedly found the same missing skill or source. The fix may be a new specialist, a source guide, or a change to the topology.

The important step is to preserve the evidence and turn it into a reviewable proposal. How to Make an Agent System Learn describes the closeout, weekly reflection, and evolution proposal process that keeps this from becoming ad hoc tinkering.

Keep old work with its existing owner

Changing a route does not make old work disappear.

Open tickets, callbacks, recovery cases, and requester-return obligations need a clear owner during the transition. Do not copy them blindly into the replacement generation. Do not edit records until they look like they belong to the new system. That makes the history less trustworthy at the moment you need it most.

Instead, keep the predecessor available for the work it already owns. Let the new route take newly admitted work once its checks pass. Use recovery to inspect incomplete old work before any action. Reliable Agent Work Needs Tickets, Locks, and Recovery covers why blind replay and casual record edits are unsafe. Retire the old path only when it has no remaining obligations and the new path has enough real evidence.

This takes longer than deleting the old endpoint. It is also much easier to explain if something fails during the change.

Retirement is a decision, not cleanup

An old route should not be retired just because a new one exists.

I want explicit exit criteria:

• the new source and live configuration have been checked;
• normal requests reach the intended semantic owner;
• duplicate and fallback behavior converges correctly;
• owner callbacks and requester return work;
• representative product work has been useful; and
• the old route has no open work that still depends on it.

The exact evidence will differ by system. The principle does not: the old path is rollback protection until the new path earns trust.

That is also why live/source drift should be reported rather than hidden. A newer role definition in a repository may be a promising future generation, not a fact about the endpoint doing work today.

Change the system deliberately

An evolving agent system is not one that changes itself freely. It is one that can learn from work, propose a change, build it in a controlled state, prove each claim, and retire the old path only when the evidence supports it.

This is slower than editing a prompt in place. It is faster than discovering later that a migration created duplicate decisions, lost a callback, or replaced the one role that could explain an unfinished request.

The practical lesson is simple: treat agent changes as live operational changes. Define the new system clearly, keep the current one legible, and make the transition prove itself before you depend on it.