---
title: "AgentCore Runtime versioning and endpoints — immutable versions, and the endpoint that points at one"
date: 2026-06-15
service: "Amazon Bedrock AgentCore"
component: "Runtime"
tags: [agentcore, runtime, versioning, endpoints, default-endpoint, immutable-versions, qualifier, blue-green, invoke-agent-runtime, update-agent-runtime-endpoint, list-agent-runtime-versions, live-version, target-version, lifecycle-states, cloudformation]
source: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agent-runtime-versioning.html
verified_on: 2026-06-15
url: https://vanemmerik.ai/aws-ai/2026-06-15.html
---

# AWS AI Daily · 2026-06-15

## AgentCore Runtime versioning — immutable versions, and the endpoint that points at one

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.

    # Move "production" onto a specific version — explicitly, when you choose to
    bedrock_agentcore_client.update_agent_runtime_endpoint(
        agentRuntimeId="agent-runtime-12345",
        endpointName="production",
        agentRuntimeVersion="2")

≈ 7 min read · Amazon Bedrock AgentCore · Runtime

## 01 · Automatic, 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.

## 02 · Endpoints 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.

## 03 · DEFAULT 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.

## 04 · The 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:

| Change | Version behavior | Latest | Endpoint behavior |
| --- | --- | --- | --- |
| Initial creation | Creates V1 | V1 | `DEFAULT` → V1 |
| Protocol change | New version | V2 | `DEFAULT` auto-updates to V2 |
| Create `PROD` endpoint on V2 | No new version | V2 | `PROD` → V2 |
| Container image update | New version | V3 | `DEFAULT` → V3, `PROD` stays on V2 |
| Update `PROD` to V3 | No new version | V3 | `PROD` → V3 |
| Network settings change | New version | V4 | `DEFAULT` → V4, `PROD` stays on V3 |

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.

## 05 · Endpoint 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.

## 06 · Selecting 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.

## Limits 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`.

## Try it in five minutes

Stand up two channels off one runtime and watch them diverge:

    # 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.

---

**Verified against the official AWS docs on 2026-06-15.**

Sources:

- AgentCore Runtime versioning and endpoints — https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agent-runtime-versioning.html
- Invoke an AgentCore Runtime agent — https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-invoke-agent.html
- InvokeAgentRuntime API Reference (the `qualifier` parameter) — https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html
- AWS::BedrockAgentCore::RuntimeEndpoint (CloudFormation) — https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrockagentcore-runtimeendpoint.html

If the docs change, this tip is a snapshot of that day — check the sources for current behaviour.

---

*This page — research, writing, verification, and deployment — was built by Claude Cowork. No human touched the prose, the layout, or the upload pipeline. A daily experiment by Monty van Emmerik · vanemmerik.ai*