The Runtime Object Model

AgentCore Runtime is the hosting primitive of the platform. You write an agent in any framework — Strands, LangGraph, CrewAI — or none at all, wrap it so it exposes a small standardized wire contract (HTTP / MCP / A2A / AG-UI), package it as an ARM64 container (or a direct-code zip), and hand it to AWS. AWS then runs it in a managed, serverless environment where every user session gets its own dedicated microVM with isolated CPU, memory, and filesystem.

The critical thing to internalize before writing code: when you "deploy an agent," you are not deploying one thing. You are creating a small graph of related resources — a runtime, one or more versions, one or more endpoints — and at request time you create sessions against an endpoint. Get this object model wrong and you will struggle to reason about rollbacks, zero-downtime updates, and why an invoke is hitting the code you didn't expect.

Sessions can live up to 8 hours, support streaming and async/background work, and are invoked through the InvokeAgentRuntime data-plane API using an agent runtime ARN plus a caller-supplied runtimeSessionId. We will unpack every term in that sentence below.

The top of the object model is the AgentCore Runtime — the agent runtime resource. This is the containerized app that hosts your agent or tool. You create it on the control plane with CreateAgentRuntime, and it is versioned from birth.

Every runtime is addressed by an agent runtime ARN, which looks like this:

arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-XXXX

That ARN is the handle you pass to the data plane every time you invoke the agent. The resource itself holds no live conversation state — it is the definition of the deployable unit. The actual configuration (which container image, which protocol, which network mode) lives one level down, in versions.

A single AWS account can hold up to 1,000 agent runtimes as of writing (adjustable) — verify the live quotas page before you design around any limit.

A version is an immutable configuration snapshot — it captures the container image, the protocol mode, and the network configuration at a single point in time. Versions are the unit of "what code/config is actually running."

Two rules drive everything:

1. CreateAgentRuntime auto-creates Version 1 (V1). You never create V1 explicitly — it appears the moment the runtime is created.
2. Every UpdateAgentRuntime creates a new version. Updates never mutate an existing version in place. Push a new image and you get V2; push again and you get V3. Old versions remain intact.

Because old versions are never destroyed by an update, rollback is just pointing an endpoint back at an earlier version — no rebuild, no redeploy. This is the entire payoff of the immutable-snapshot design.

import boto3
control = boto3.client("bedrock-agentcore-control")   # CONTROL plane

# Inspect the version history of a runtime
resp = control.list_agent_runtime_versions(
    agentRuntimeId="MyAgent-XXXX"
)
# Iterate the returned summaries; confirm the exact response key/field
# names against the live boto3 / API reference for your SDK version.
for v in resp.get("agentRuntimes", []):
    print(v.get("agentRuntimeVersion"), v.get("status"))

An account can hold up to 1,000 versions per agent as of writing (verify live). In practice you will never approach that — but you should expect the list to grow with every deploy, which is exactly what makes a rollback possible.

An endpoint (an alias) is an addressable access point that points to a specific version. Each endpoint has its own ARN. Endpoints are the indirection layer that lets you change what runs without changing what callers address.

Two flavors:

• DEFAULT — auto-created with the runtime and always tracks the latest version. If you do nothing special, your invokes hit DEFAULT, and DEFAULT follows your most recent update.
• Custom endpoints — created with CreateAgentRuntimeEndpoint. You wire these to a chosen version yourself, which is how you build patterns like a pinned prod alias and a moving staging alias.

At invoke time you select which endpoint to hit with the qualifier parameter on InvokeAgentRuntime. Omitting it (or passing "DEFAULT") targets the DEFAULT endpoint:

resp = data.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-XXXX",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "Tell me a joke"}).encode(),
    qualifier="DEFAULT",   # or a custom endpoint name to pin a version
)

Endpoints move through lifecycle states: CREATING, CREATE_FAILED, READY, UPDATING, and UPDATE_FAILED. When you re-point an endpoint to a new version it transitions through UPDATING back to READY, and crucially updates are zero-downtime — in-flight traffic keeps flowing while the swap happens. An account can hold up to 10 endpoints per agent as of writing (verify live).

A session is an interaction context — the unit that holds the back-and-forth of one conversation (or one agent task) and runs in its own dedicated microVM. Sessions are identified by a caller-supplied runtimeSessionId, or one is generated on the first invoke if you don't pass it.

The runtimeSessionId is how AgentCore knows that two invokes belong to the same conversation: reuse the same ID across related calls and they share the same microVM (and its in-memory context). Use a fresh ID and you get a fresh microVM. The commonly cited rule is that the ID must be at least 33 characters (a UUID is 36, so str(uuid.uuid4()) is a safe default) — confirm the exact minimum in the live API reference before relying on it:

import json, uuid, boto3
data = boto3.client("bedrock-agentcore")              # DATA plane
session_id = str(uuid.uuid4())                        # >= 33 chars; reuse for one conversation

resp = data.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-XXXX",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "What's the weather?"}).encode(),
    qualifier="DEFAULT",
)
print(json.loads("".join(c.decode("utf-8") for c in resp.get("response", []))))

One ownership rule you must not miss: AWS does NOT map sessions to users. As the AWS docs put it, "your client backend should maintain the relationship between users and their session IDs." Picking session IDs, reusing them for continuity, and enforcing per-user session caps is your responsibility — the platform only sees opaque IDs.

A session remains valid until the AgentCore Runtime ARN is deleted, but its microVM is ephemeral: it is torn down (and its memory sanitized) on idle timeout (default 15 min), at the max compute lifetime (default 8 hours), or on an explicit StopRuntimeSession. (Session isolation as a security boundary gets its own lesson; here, just hold the idea that a session = one interaction context keyed by runtimeSessionId.)

Every operation on a runtime lands on one of two planes, and they are genuinely separate — different endpoints, different API sets, different boto3 clients, and different IAM actions. Mixing them up is one of the most common early mistakes.

Control plane — manage the resources. Region endpoint bedrock-agentcore-control.{region}.amazonaws.com. boto3 client name bedrock-agentcore-control. Operations include CreateAgentRuntime, UpdateAgentRuntime, CreateAgentRuntimeEndpoint, GetAgentRuntime, ListAgentRuntimes, and ListAgentRuntimeVersions.

Data plane — invoke the resources. Region endpoint bedrock-agentcore.{region}.amazonaws.com. boto3 client name bedrock-agentcore. The primary operation is InvokeAgentRuntime (others include InvokeAgentRuntimeCommand, InvokeAgentRuntimeWithWebSocketStream, and StopRuntimeSession). The SDK method is invoke_agent_runtime(...).

import boto3

control = boto3.client("bedrock-agentcore-control")   # create / update / list
data    = boto3.client("bedrock-agentcore")            # invoke

# Control plane: list runtimes and inspect one
control.list_agent_runtimes()
control.get_agent_runtime(agentRuntimeId="MyAgent-XXXX")

# Data plane: invoke it (see the sessions section for the full call)
# data.invoke_agent_runtime(agentRuntimeArn=..., runtimeSessionId=..., payload=...)

For SigV4-authenticated invokes, the governing IAM action is bedrock-agentcore:InvokeAgentRuntime. (Delegated user-id invokes use a separate action, bedrock-agentcore:InvokeAgentRuntimeForUser — covered in the Identity lessons.)