Agent Migration: Reference Set and Return Path

An automation migration changes code, tools, permissions or runtime conditions. The team needs a written account of current behavior before it can decide whether a new implementation is acceptable.

Define the behavior worth carrying forward

Start with the old system's inputs, source state, decisions, tool calls and user-visible outcomes. Preserve the process context that affected each result. A sentence-level comparison gives a noisy signal when the important invariant is a decision or a field update.

The reference set should cover:

• ordinary requests and common intents;
• refusals and out-of-scope requests;
• tools, integrations and permission states;
• retries, duplicate events and missing data;
• rare cases whose consequences deserve deliberate review.

The process owner should mark known legacy defects before the set becomes a release target. This keeps an old mistake from turning into a new requirement.

Build the reference set

For every case, store:

Separate exact fields from flexible language. A response can change wording while keeping the decision, permission and transferred data correct.

Classify each difference

Each difference needs an owner, impact and decision. Useful categories include:

• intended product change;
• legacy defect that the replacement corrects;
• replacement defect;
• harmless wording or formatting change;
• missing evidence that needs another case.

The register becomes the migration's decision log. A total match percentage is a context signal; a single unresolved permission or payment-related difference may block traffic even when many low-impact cases match.

Exercise the target environment

The replacement must run with the connections, credentials, limits, logging and failure handling it will use after release. A saved comparison cannot reveal an expired token, a missing queue, a different index or an incorrect permission.

Run a shadow path against current traffic while the old system remains authoritative. Review the proposed outputs, tool calls and exceptions. Keep the source system available until the owner has decided how to handle the open differences.

Make return reversible

The return path names:

• the person who can order the return;
• the signal that triggers it;
• the switching procedure and access required;
• handling of cases already in flight;
• reconciliation of records written during the switch;
• the evidence retained after the return.

Exercise the procedure in the target environment. A controller that can switch traffic is only one part of a safe return; the team also needs a plan for partial work and duplicated events.

Evidence for a migration decision

The owner should have four artifacts:

1. a reference set with legacy defects labeled;
2. a discrepancy register with closed and open decisions;
3. a target-environment record from shadow or limited traffic;
4. a return record with reconciliation steps.

Open high-impact differences keep the switch on hold. A small reversible segment may be appropriate when the owner can inspect the evidence and return within the defined observation window.

Details of the method are available in the agent migration case. If an automation is approaching retirement, discuss a migration scope before traffic moves.