Migrate to Claude Sonnet 5 or Opus 4.8: Complete Guide (2026)

Claude Opus 4.8 shipped May 28, 2026. Claude Sonnet 5 followed June 30, 2026. If your agents are still pinned to Opus 4.7, 4.6, or an older Sonnet, this guide walks through a safe migration on Paperclip — including which model to pick, and the things that typically go wrong in the first 48 hours.

Migration summary: One-line change in agent config. Prompts stay mostly identical. Rollback is 30 seconds. Expected outcome for agents moving to Sonnet 5: similar or better quality on tool-use/support tasks at roughly a third of Opus pricing. For agents moving to Opus 4.8: measurable lift on hard coding tasks, unchanged per-token price vs 4.7.

Before you start — pick your target model

Not every agent should land on the same model. Use your current agent’s job to decide:

Your agent does	Migrate to
Deep, multi-file autonomous coding	Opus 4.8
Browser/tool-driving, computer use	Sonnet 5
General support, research, knowledge work	Sonnet 5
Simple routing/classification	Stay on Haiku 4.5

Sonnet 5 scores close to Opus 4.8 on general knowledge work (GDPval-AA v2: 1,618 vs 1,615) and ahead on computer-use tasks (81.2% OSWorld-Verified) — at roughly a third of the price ($2/$10 vs $5/$25 per million tokens, introductory pricing through August 31, 2026). Opus 4.8 keeps a clear lead on the hardest autonomous coding (SWE-bench Pro: 69.2% vs 63.2%).

Validation checklist

Do these three things before touching a single agent:

1. Pin your current success-rate baseline. Open your Paperclip monitoring dashboard and note, per agent: success rate over the last 7 days, median tokens per successful run, median latency, error-to-success ratio.

2. Identify one low-risk agent to migrate first. Something that runs frequently enough to produce a signal in 24-48 hours but isn’t mission-critical — internal tooling, support-triage with human review, research agents with reviewed output.

3. Confirm your BYOK Anthropic API key is current. Paperclip → Settings → Providers → Anthropic → regenerate if it’s been more than 6 months.

Step 1 — Update the model ID

Via the HostAgentes dashboard

1. Open the agent → Settings → Model
2. Select Claude Sonnet 5 or Claude Opus 4.8 from the dropdown
3. Leave temperature, max tokens, and system prompt unchanged initially
4. Save — no redeploy, no cold start.

Via paperclip.yaml

  agent:
    name: "support-handler"
    model:
      provider: anthropic
-     id: claude-opus-4-7
+     id: claude-sonnet-5
      temperature: 0.3
      max_tokens: 8000

Commit, push, Paperclip reloads the agent config on next run.

Via the Anthropic API directly

- model: "claude-opus-4-7"
+ model: "claude-sonnet-5"

Tool definitions, system prompt, and stop sequences stay the same.

Step 2 — Re-baseline token counts (Sonnet 5 only)

Sonnet 5 ships an updated tokenizer: the same input can map to 1.0–1.35× more tokens than on Sonnet 4.6 or Opus models, depending on content type. Don’t assume the lower per-token price translates directly to lower total cost — measure tokens-per-task after the swap, not before.

Step 3 — Consider Dynamic Workflows (Opus 4.8 only)

If you’re migrating a large-scope research or refactor agent to Opus 4.8, its Dynamic Workflows feature (research preview) can plan a task and dispatch hundreds of parallel subagents in a single session:

agent:
  name: "autonomous-refactor"
  model:
    provider: anthropic
    id: claude-opus-4-8
  dynamic_workflows: true

This is opt-in and still in preview — test it on a non-critical agent first.

Step 4 — Monitor for 48 hours

Success rate

Should hold steady or rise. If an agent moved from Opus to Sonnet 5 and success rate drops more than a few points on hard tasks, that agent likely needs to stay on Opus 4.8.

Tokens per successful task

For Sonnet 5 migrations, compute this fresh — don’t extrapolate from the old model’s token counts given the tokenizer change.

Total spend

Should fall for agents moved to Sonnet 5, given the ~2.5x price gap even after accounting for more tokens per call. If it doesn’t, check for accidentally elevated max_tokens or effort settings.

Latency and tool call patterns

Watch for regressions, especially on agents that lean heavily on tool-calling — Sonnet 5 was specifically built for this, so patterns should be at least as clean as before.

Things that typically go wrong

1. Assuming Sonnet 5’s price cut maps directly to cost cut

The tokenizer change means it doesn’t always. Measure, don’t assume.

2. Keeping coding-heavy agents on Sonnet 5 when they need Opus

If a coding agent’s success rate drops after moving to Sonnet 5, that’s a signal it’s in the ~6-point SWE-bench Pro gap where Opus 4.8 still matters. Move it back.

3. Prompts over-tuned for older model quirks

Phrases like “think carefully,” “do not skip steps” were often compensating for older model weaknesses. On the current lineup they can cause over-reasoning and inflate output tokens. Remove them one at a time and A/B test.

4. Forgetting BYOK rate limits on new model IDs

Some Anthropic accounts need explicit verification before new model IDs unlock at full rate limits. Check your Anthropic console if you see 403s.

Rollback plan

Via dashboard: Same dropdown, flip back to the previous model. Zero downtime.

Via yaml:

  model:
    provider: anthropic
-   id: claude-sonnet-5
+   id: claude-opus-4-7

Commit, redeploy, done. Anthropic keeps prior model versions available for a transition period, so there’s no urgent forcing function — migrate on your own timeline.

Rolling migration across multiple agents

Once one agent has run cleanly on its new model for 3-5 days, batch-migrate the rest:

1. Dashboard → Fleet view
2. Select agents by tag (e.g., environment=production)
3. Bulk action → Update model
4. Monitor fleet-level metrics for another 48 hours

FAQ

Should I go straight to Sonnet 5, or via Opus 4.8 first? Skip intermediate versions — go directly to whichever of Sonnet 5 or Opus 4.8 fits the agent’s job, per the table above.

Will migrating break my existing prompts? Unlikely for prompt structure. The main gotcha is Sonnet 5’s token counts changing due to its updated tokenizer — re-measure cost, don’t assume.

Does Opus 4.8 cost more to run than 4.7? No — per-token pricing is unchanged ($5/$25 standard). Sonnet 5 is meaningfully cheaper than any Opus tier.

What if my BYOK Anthropic account isn’t approved for the new models yet? Check your Anthropic console — new model IDs sometimes need billing re-verification before they unlock.

---

Related: Deploy Sonnet 5 & Opus 4.8 on Paperclip → · Sonnet 5 & Opus 4.8 vs GPT-5.6 vs Gemini → · Paperclip + Anthropic integration →