CertSafari
    Anthropic Claude Certified Developer – Professional (CCDV-P)· Lessons

    Domain 2 · Lesson 7/25

    Model migration and prompt versioning with progressive rollout

    Production MCP and Change Management

    8 min read
    5% of exam
    7 sources
    Published 19 Nov 2026
    Docs as of 18 Nov 2026

    What you will be able to do

    • Pin model snapshots and track model retirement dates separately for each platform
    • Turn a model migration checklist into tests for breaking behaviour changes
    • Promote, canary and roll back prompt versions by changing a pinned version number instead of redeploying code
    • Order server, prompt and rollback changes so that no step sends calls the other side rejects

    1.Migrating to a new model version

    A model change can alter an agent's behaviour without a single line of code changing. It needs the same change control as a deploy, and the model lifecycle sets the deadline. Models move from Active to Legacy, then Deprecated, then Retired. A deprecated model still works and has a named replacement and a retirement date. After that date, requests to it fail.

    Pin the snapshot so the model changes only when you change it. claude-haiku-4-5 is a convenience alias that resolves to the pinned snapshot claude-haiku-4-5-20251001. Production configuration should name the snapshot, so that a migration is an edit you can review. Pinning differs by platform, because the same model has a different identifier on each one:

    One model, four platform identifiers
    PlatformModel ID for Claude Haiku 4.5
    Claude APIclaude-haiku-4-5-20251001
    Amazon Bedrock (bedrock-runtime)global.anthropic.claude-haiku-4-5-20251001-v1:0
    Claude Models on Google Cloud (Google managed)claude-haiku-4-5@20251001
    Microsoft Foundryclaude-haiku-4-5

    Retirement dates can also differ by platform. The published dates cover Anthropic-operated platforms. Amazon Bedrock and Google-managed Google Cloud set their own retirement schedules, so a model can be deprecated on one platform and not on another. A multi-cloud deployment needs a migration calendar for each platform, not one date for all of them.

    A migration guide is a list of breaking changes, and each item should become a test you run against the new snapshot before you switch traffic. Some items fail loudly. Claude Opus 4.6 and later reject assistant-message prefills, so any request that still sends one returns an error. Other items fail quietly: a new refusal stop reason your code must handle, or a change in how tool string parameters treat trailing newlines. The newline change can alter the arguments your MCP tools receive without causing any error. Replay real production requests, including tool calls, through the new snapshot and compare the outputs, not just the status codes. Then review the prompts themselves against current prompting guidance.

    Checkpoint 1 of 3· Check yourself

    A production config names claude-haiku-4-5 rather than a dated snapshot. What is the migration risk?

    Sources123

    2.Versioned prompts, canaries and rollback

    A prompt can be managed as a versioned server-side resource instead of a string in code. In Managed Agents, every agents.update creates a new immutable version, and each session chooses which version it runs. A caller that passes the bare agent ID gets the latest version. Any update, reviewed or not, then reaches production at that caller's next session. Production callers should pin an explicit version. The pinned number becomes the gate: anyone can create a new version, but changing the production pin goes through review.

    A progressive rollout then works like this:

    1. Create the new version. It receives no traffic until you promote it.
    2. Score it against a labelled test set.
    3. Send a fraction of traffic to it as a canary.
    4. Promote it, or roll back by re-pinning the previous version, which needs no deploy.

    The gate has to measure task quality. In the worked example, a broadened routing rule kept three teams at 5/5 but dropped billing from 4/5 to 2/5. Latency and HTTP success rates would have looked identical for both versions.

    Long conversations show why the version is pinned when a session starts. A session pins its version at the start and keeps it until the session ends, so a rollback changes only which version new sessions start on. Conversations already running keep the version they began with instead of switching prompts mid-dialogue. Managed MCP removals behave the same way: a running claude -p job keeps a removed server until the job ends.

    When a change spans components, the order of deploys matters. Suppose a revised prompt needs a new tool parameter. If the prompt ships first, the agent sends an argument the server does not accept yet, and every such call fails with an invalid-arguments error until the server catches up. Deploy the server change first, as an additive change that accepts the new parameter and the old calls alike, and only then promote the prompt version. This order also keeps rollback safe: pinning the old prompt again sends calls that the new server still accepts.

    Checkpoint 2 of 3· Check yourself

    A rollback only affects work that starts after it, the same way a session keeps the prompt version it started with. Mid-rollout, you remove a server from managedMcpServers while one engineer has an interactive Claude Code session open and a nightly claude -p job is halfway through. What happens to the removed server?

    Sources456

    3.Stored conversations across a model switch

    Stored conversations are state that a model migration has to carry, and thinking blocks are the part that can vanish without a trace. When a conversation moves between models, whether its earlier reasoning survives depends on the pair. Moving onto Claude Haiku 5.5 from Claude Haiku 4.5 or earlier, Claude Sonnet 5 or earlier, or Claude Opus 4.8 or earlier keeps the reasoning. Moving onto it from any other model, a long-running Claude Opus 5.5 conversation downshifted for cost, for example, does not: the API drops that model's thinking blocks without an error. Status codes stay green while the answers get worse.

    Account boundaries cause the same silent loss. Thinking blocks from Claude Haiku 5.5 work only in the account that produced them, or one linked to it. A service that keeps conversations for several customers in one store and replays them through a single shared account sends blocks that are dropped before the model sees them, and each request still succeeds. Replay each conversation through the account that produced it.

    History edits cost more than reasoning. A thinking block stays valid only while the system prompt, the tools and every earlier message are unchanged, so a prompt update that rewrites old turns invalidates every later block. A failed prefix check might or might not return a 400 error, which means a test that watches only for errors misses half the cases. To change instructions mid-conversation, add a mid-conversation system message instead of rebuilding the history; a rebuild can draw a 400 error and loses prompt cache hits.

    Turn this into a migration test: replay a sample of stored multi-turn conversations, including ones saved under the old model and ones from other accounts, through the new snapshot, and compare answer quality against the old baseline rather than comparing status codes.

    Checkpoint 3 of 3· Check yourself

    A service stores conversations for several customers and replays all of them through one shared account, though each was produced under a different account. What happens to the Claude Haiku 5.5 thinking blocks in those histories?

    Sources73

    Sources

    (7)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “Requests to models past the retirement date will fail.”
      ↩︎ Migrating to a new model version
      “Partner-operated platforms, Claude Models on Google Cloud (Google managed) and Amazon Bedrock, set their own retirement schedules”
      ↩︎ Migrating to a new model version
      “Partner-operated platforms, Claude Models on Google Cloud (Google managed) and Amazon Bedrock, set their own retirement schedules”
      ↩︎ Exam trap 2
    2. 2.
      “claude-haiku-4-5 is a convenience alias that resolves to the pinned snapshot claude-haiku-4-5-20251001.”
      ↩︎ Migrating to a new model version
    3. 3.
      “Remove any assistant-message prefills; Claude Opus 4.6 already rejects them.”
      ↩︎ Migrating to a new model version
      “Verify tool string parameter handling for trailing newlines.”
      ↩︎ Migrating to a new model version
      “Review and update prompts following prompting best practices.”
      ↩︎ Migrating to a new model version
      “After a rebuild, a request can get a 400 error, and prompt cache hits are lost.”
      ↩︎ Stored conversations across a model switch
    4. 4.
      “Treat the pinned version number as the gate for changing prompts.”
      ↩︎ Versioned prompts, canaries and rollback
      “For higher-stakes agents, route a fraction of traffic to a new version and compare (as this notebook does) before promoting fully.”
      ↩︎ Versioned prompts, canaries and rollback
      “Have production callers pin to an explicit version, not the bare agent ID. New versions stay invisible until you promote one.”
      ↩︎ Exam trap 1
      “Every agents.update produces a new immutable version, and sessions choose which version to use by ID.”
      ↩︎ Prediction
    5. 5.
      “A non-interactive (-p) run keeps it until it ends.”
      ↩︎ Versioned prompts, canaries and rollback
      “Remove a server: a running interactive session disconnects it once it reads the changed settings. A non-interactive (-p) run keeps it until it ends.”
      ↩︎ Checkpoint
    6. 6.
      “Protocol Errors: Standard JSON-RPC errors for issues like: Unknown tools Invalid arguments Server errors”
      ↩︎ Versioned prompts, canaries and rollback
    7. 7.
      “the API drops the block before the model receives it, and the request succeeds without that reasoning”
      ↩︎ Stored conversations across a model switch
      “A Claude Haiku 5.5 thinking block stays valid only while everything sent before it is unchanged”
      ↩︎ Stored conversations across a model switch

    Ready to test yourself?

    Practise Anthropic Claude Certified Developer – Professional (CCDV-P) in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.