Runtime versioning.

You shipped an agent. Now you want a staging copy on last week's build, a production copy you only move on purpose, and a DEFAULT that always tracks the newest code. AgentCore Runtime gives you all three without a deployment system of your own: every change to a runtime mints a new immutable version, and endpoints are the named pointers that decide which version actually serves traffic. Understand the version/endpoint split and blue-green for agents is two API calls.

01Automatic, immutable versioning

You never call a "publish version" API by hand. AgentCore versions a runtime for you:

• When you create an AgentCore Runtime, it automatically creates version 1 (V1).
• Each update to the runtime creates a new version with a complete, self-contained configuration.
• Versions are immutable once created — they don't change underneath you.
• Each version contains all the configuration needed for execution — there's no partial diff to reassemble.

That last point is the one that matters operationally: a version isn't a delta against the previous one, it's a full snapshot. Roll an endpoint back to V2 and you get exactly the container image, protocol, and network settings V2 had — nothing leaks forward from V3.

02Endpoints point at versions

A version is inert until an endpoint references it. Endpoints are the addressable, named pointers you actually invoke:

• The DEFAULT endpoint automatically points to the latest version of your runtime.
• Endpoints can point to specific versions, letting you maintain different environments — development, staging, production — off one runtime.
• When you update the runtime, the DEFAULT endpoint is automatically updated to point to the new version.
• Any other endpoint must be explicitly updated to point to a new version.

In CloudFormation the endpoint is AWS::BedrockAgentCore::RuntimeEndpoint, and its shape tells the whole story: a Name, the AgentRuntimeId it belongs to, and an optional AgentRuntimeVersion it pins. Leave the version off and it tracks the latest; set it and you've nailed the endpoint to one snapshot. The endpoint name is short by design — up to 48 characters, ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ — because it's the human-readable handle you'll pass at invoke time.

03DEFAULT vs named endpoints — the blue-green lever

This is the whole feature in one idea. DEFAULT is your "always newest" channel: every agentcore deploy (or UpdateAgentRuntime) bumps the version and DEFAULT follows instantly, which is perfect for a dev loop and dangerous for production. A named endpoint pinned to a version is your stable channel: it does not move when you push new code. It moves only when you call UpdateAgentRuntimeEndpoint with a new agentRuntimeVersion.

So the safe promotion pattern is: push code freely (DEFAULT and your dev clients see it immediately), test against DEFAULT, and when you're satisfied, point production at that version with one explicit call. Roll back the same way — re-point production at the previous integer. Because versions are immutable snapshots, the rollback target is byte-for-byte what it was.

04The versioning scenario table

The docs spell out exactly when a new version is born and how endpoints react. Note that a new endpoint never creates a version — endpoints and versions are independent axes:

The takeaway: protocol changes, container image updates, and network/security setting changes each cut a new version; creating or re-pointing an endpoint does not. DEFAULT always chases the latest version automatically; PROD sits still until you move it.

05Endpoint lifecycle states

An endpoint is itself a managed resource with its own state machine, so a deploy or promotion can be observed (and can fail) independently of the runtime:

• CREATING — initial state while the endpoint is being created.
• CREATE_FAILED — creation failed (permissions, container, or other issues).
• READY — the endpoint is accepting requests.
• UPDATING — the endpoint is moving to a new version.
• UPDATE_FAILED — the update operation failed.

In CloudFormation the endpoint surfaces matching attributes you can read with Fn::GetAtt: Status, LiveVersion (the version currently deployed and serving), TargetVersion (the version it's trying to reach), and FailureReason. The LiveVersion/TargetVersion pair is what makes an in-flight promotion legible — during an UPDATING window they differ, and a failed update leaves LiveVersion where it was so traffic keeps flowing on the last good snapshot.

06Selecting an endpoint at invoke time

You choose the channel per call. InvokeAgentRuntime takes an optional qualifier — "an endpoint name that points to a specific version. If not specified, Amazon Bedrock AgentCore uses the default endpoint of the agent runtime." So an unqualified invoke hits DEFAULT; passing qualifier="production" routes the same request to whatever version your production endpoint is pinned to.

import boto3

client = boto3.client("bedrock-agentcore")
resp = client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=session_id,      # 33–256 chars
    qualifier="production",           # omit this to hit DEFAULT
    payload=payload)

To see what's out there, ListAgentRuntimeVersions enumerates every immutable version of a runtime and ListAgentRuntimeEndpoints lists the endpoints (and, via the live/target fields, which version each is serving). That pairing — versions on one axis, endpoints on the other — is the entire mental model.

07Limits worth knowing

• DEFAULT is a live wire. It re-points to the newest version automatically on every runtime update. Never let production clients invoke without a qualifier unless you genuinely want them on the bleeding edge.
• Named endpoints never auto-advance. A pinned endpoint stays on its version until you call UpdateAgentRuntimeEndpoint — convenient for stability, but it also means a forgotten endpoint can sit on stale code indefinitely.
• Versions are integers, and they're capped. The CloudFormation AgentRuntimeVersion pattern is ^([1-9][0-9]{0,4})$ — version numbers run 1 through 99999, monotonically, one per update.
• Endpoint names are short and immutable in CFN. Max 48 characters, and changing Name (or the AgentRuntimeId) in CloudFormation forces a replacement of the endpoint; only AgentRuntimeVersion, Description, and Tags update in place with no interruption.
• A failed update doesn't drop traffic. UPDATE_FAILED leaves LiveVersion on the previously deployed snapshot, so the endpoint keeps serving the last good version while you investigate FailureReason.

08Try it in five minutes

Stand up two channels off one runtime and watch them diverge. DEFAULT already tracks the latest version; you add a stable production endpoint and promote it on your own schedule:

# 1. You already have a runtime; DEFAULT tracks its latest version.
#    Create a stable PROD endpoint pinned to version 1.
aws bedrock-agentcore-control create-agent-runtime-endpoint \
    --agent-runtime-id agent-runtime-12345 \
    --name production \
    --agent-runtime-version 1

# 2. Push a change (new container image) -> a new version, say V2, is minted.
#    DEFAULT now serves V2; production is still on V1.
aws bedrock-agentcore-control list-agent-runtime-versions \
    --agent-runtime-id agent-runtime-12345

# 3. Promote production to V2 — explicitly, when you're ready.
aws bedrock-agentcore-control update-agent-runtime-endpoint \
    --agent-runtime-id agent-runtime-12345 \
    --endpoint-name production \
    --agent-runtime-version 2

Invoke with no qualifier to hit DEFAULT (latest), then invoke again with --qualifier production and confirm the two channels can be on different versions at the same time. That gap — DEFAULT racing ahead while production holds — is exactly the safety margin versioning buys you.