Migrating a Workflow to a Claude Managed Agent Safely

You have an existing workflow that works — a rules engine, a pile of scripts, a team of people following a runbook — and you want to move it onto a Claude Managed Agent. The temptation is to rip out the old system on a Friday and flip on the agent Monday. Resist it. The fastest way to lose trust in agents, internally and with customers, is a big-bang cutover that fails in a way no one was watching for. Migration done well is boring, incremental, and reversible.

This post is a playbook for moving a real workflow onto a Claude Managed Agent without betting the business on it. The throughline: run the agent in the shadow of the old system first, expand its authority gradually as evidence accumulates, and keep a rollback path live the entire time. You are not replacing a process; you are auditioning a replacement under increasing responsibility.

Key takeaways

• Never big-bang a workflow onto an agent; migrate in stages with a rollback path at every stage.
• Start in shadow mode — the agent runs alongside the old system and proposes, the old system still decides.
• Decompose the workflow and migrate the lowest-risk, highest-volume step first to build evidence.
• Promote the agent from suggest to assist to act only as evals and shadow metrics clear each bar.
• Keep the old path warm and reversible until the agent has proven itself on real traffic over time.

Map the workflow before you touch it

Before any code, write down the existing workflow as discrete steps with their inputs, outputs, decision points, and failure handling. This map is the contract the agent has to honor, and most failed migrations skip it — they hand the agent a fuzzy "do what Dana does" brief and are surprised when it misses an edge case Dana handles by reflex. The map surfaces the implicit rules so you can encode them deliberately.

The map also tells you where to start. Some steps are high-risk and irreversible — issuing a refund, sending a contract — while others are high-volume and low-stakes — classifying an inbound request, drafting a first response. You want to migrate the low-stakes, high-volume steps first, because they generate the most evidence per unit of risk. Save the irreversible steps for after the agent has earned trust on the cheap ones.

The staged rollout

The core of safe migration is a ladder of increasing authority. At each rung the agent does more, but only after the previous rung produced the evidence to justify the promotion. The rungs are shadow, suggest, assist, and act.

flowchart TD
  A["Existing workflow mapped"] --> B["Shadow: agent runs, output discarded"]
  B --> C{"Shadow agrees with old system?"}
  C -->|No| D["Diagnose divergence + refine"]
  D --> B
  C -->|Yes, consistently| E["Suggest: human sees agent proposal"]
  E --> F{"Humans accept proposals?"}
  F -->|No| D
  F -->|Yes| G["Assist: agent acts on low-risk cases"]
  G --> H{"Eval + production metrics hold?"}
  H -->|No| I["Roll back to suggest"]
  H -->|Yes| J["Act: agent owns the step, monitored"]

In shadow mode the agent processes real inputs in parallel with the existing system, but its output is logged and discarded, never acted on. You compare the agent's decisions against the old system's and against eventual real outcomes. This is the safest possible test because the agent cannot affect anything — and it surfaces divergences on real traffic that no synthetic eval would have found.

Once the agent agrees with the trusted system consistently, promote it to suggest: a human still owns the decision, but the agent's proposal is shown to them. Acceptance rate becomes your signal. When humans routinely accept the proposals, move to assist — the agent acts autonomously on the low-risk slice while humans handle the rest. Only when assist holds up on production metrics and evals do you let the agent act as the owner of the step, with monitoring and a kill switch in place.

Keep a rollback path live

Every stage must be reversible with one action. The old system does not get deleted the moment the agent goes live; it goes dormant but warm, ready to resume instantly if a metric craters. Concretely, that means a feature flag or routing switch that sends traffic back to the legacy path, and an explicit, documented threshold — if error rate, customer complaints, or a key business metric crosses a line, you flip back without a meeting.

This is what separates a confident rollout from a risky one. When everyone knows the rollback is one switch away and has been tested, the team is willing to advance the agent's authority faster, because the downside is bounded. Counterintuitively, investing in a clean rollback makes the whole migration go quicker, because each promotion is a small bet rather than a leap. Test the rollback before you need it — a rollback path you have never exercised is a hope, not a control.

Canary on a slice of traffic

When you do let the agent act, do not give it all the traffic at once. Route a small percentage — a canary — to the agent and keep the rest on the proven path. Watch the canary's outcomes against the control group on the metrics that matter: resolution rate, error rate, cost, latency, and customer sentiment. If the canary matches or beats the control, widen it gradually; if it underperforms, you have lost only a fraction of traffic and you roll the canary back.

Choose the canary slice deliberately rather than randomly where you can. Starting with a segment that is more tolerant of imperfection — internal users, a low-stakes region, off-peak hours — gives you a softer landing for the inevitable early surprises. Expand to higher-stakes traffic only after the easy slice is solid.

Stage	Agent authority	Promote when	Rollback to
Shadow	None (output discarded)	Agrees with old system consistently	n/a
Suggest	Proposes to a human	Humans accept proposals	Shadow
Assist	Acts on low-risk slice	Evals + metrics hold on canary	Suggest
Act	Owns the step	Sustained parity or better	Assist / legacy

Common pitfalls

• Big-bang cutover. Replacing the whole workflow at once removes your ability to compare and your ability to roll back gracefully. Stage it.
• Migrating the riskiest step first. Irreversible actions generate the least evidence per unit of risk. Start with high-volume, low-stakes steps.
• Deleting the legacy path too soon. Keep it warm and reachable by a switch until the agent has proven itself over real time, not a few good days.
• No quantitative promotion criteria. "It feels good" is not a gate. Define the metric and threshold that earns each promotion before you start.
• An untested rollback. A rollback you have never exercised will fail when you need it most. Drill it during a calm period.

Migrate a workflow in 6 steps

1. Map the existing workflow into discrete steps with inputs, outputs, decisions, and failure handling.
2. Pick the lowest-risk, highest-volume step to migrate first and build an eval suite for it.
3. Run the agent in shadow mode against real traffic and compare its decisions to the trusted system.
4. Promote through suggest, assist, and act, requiring a defined metric threshold to clear each rung.
5. Canary real traffic on a small, tolerant slice and widen only as outcomes match or beat the control.
6. Keep the legacy path warm behind a tested switch until the agent has sustained parity over time.

Frequently asked questions

How long should an agent stay in shadow mode?

Long enough to see the workflow's real distribution of cases, including the rare and the seasonal ones, and to confirm the agent agrees with the trusted system across them. That is measured in volume and variety of cases observed, not a fixed number of days. If your traffic is bursty or seasonal, shadow through at least one full cycle before promoting.

What if the agent and the old system disagree in shadow mode?

Each disagreement is a gift — investigate it. Sometimes the agent is wrong and reveals a gap in its context or tools; sometimes the agent is right and exposes a flaw in the legacy system. Either way you learn something concrete before any customer is affected. Do not promote until disagreements are rare and the remaining ones are explainable.

Do I need a full eval suite before migrating?

You need at least a starter suite covering the step you are migrating first, and you grow it as shadow and canary surface new cases. Migration and evals are complementary: shadow mode discovers failures on real traffic, and you fold each one into the eval suite so future changes cannot reintroduce it. Begin small, expand continuously.

When is it safe to finally retire the legacy path?

When the agent has held parity or better on real traffic across a full range of conditions for long enough that a regression would have shown up, and when your rollback to a regenerated path is still feasible even after retirement. Retiring the old system is the last step, taken with evidence, not the first step taken on optimism.

Bringing agentic AI to your phone lines

CallSphere rolls its voice and chat agents onto live phone and chat workflows the same careful way — shadow, then suggest, then act, always reversible — so agents take over answering calls and booking work without a risky cutover. See it live at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.