[AWS] Migrating AgentCore runtime from V1 to V2 [AgentCore]

This article is a machine translation of the contents of the following URL, which I wrote in Japanese:

【AWS】AgentCore runtimeをV1からV2へ移行しよう【AgentCore】 #AIエージェント - Qiita

はじめに Amazon Bedrock AgentCoreの次世代のruntimeは、2026年9月18日に公開されました。公式ドキュメントではV2と呼ばれ、従来のruntimeはV1です。V2は、初期化済みのエージェントのスナップショットからセッションを復元する方式で、...

qiita.com

Introduction

The next-generation runtime of Amazon Bedrock AgentCore was released on September 18, 2026. The official documentation calls it V2, and the previous runtime is V1. V2 restores sessions from a snapshot of an already-initialized agent, so it starts faster and is billed only for what you use. For about two months after release, it was an opt-in option available only if you set platformVersion to V2.

Then, on November 12, 2026, AWS announced that the next-generation AgentCore runtime is now the default.

"Starting today, new runtimes in Amazon Bedrock AgentCore use the next generation of AgentCore runtime by default."
Source: https://aws.amazon.com/about-aws/whats-new/2026/11/new-agentcore-runtime-default/

In other words, a newly created runtime becomes V2 if you specify nothing. Existing runtimes stay on the current version (V1) until you migrate them. When V2 came out and what changed with this news is organized chronologically in the next section.

From a hands-on perspective, though, several questions come up.

• What happens to existing runtimes? Is migration necessary? What happens to running sessions and invocations during migration?
• Can I roll back?
• Can I migrate from the console? What about CloudFormation?
• Do I need to change my code?

So in this article I ran the same agent on both V1 and V2 to compare them, and tried migrating from V1 to V2 in three ways: the CLI, the Management Console, and CloudFormation. For anything the official documentation does not cover, I checked by actually running it.

This article assumes basic knowledge of AgentCore runtime (deploying an agent as a container image) and of the AWS CLI.

The verification was done on November 13, 2026 in the Tokyo Region (ap-northeast-1). AWS screens and documentation can change, so I state the date explicitly.

When V2 came out, and what changed with this news

V2 did not first appear with this news. The timeline below is organized from the official announcements and release notes. Dates follow the original wording. The release notes are written per month and do not give a day.

Sources:

• What's New (September 18, 2026): https://aws.amazon.com/about-aws/whats-new/2026/09/new-agentcore-runtime-generally-available/
• ML Blog (September 18, 2026): https://aws.amazon.com/blogs/machine-learning/the-new-agentcore-runtime-elastic-optimized-and-consistently-fast-starts/
• Release notes: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/release-notes.html
• What's New (November 12, 2026): https://aws.amazon.com/about-aws/whats-new/2026/11/new-agentcore-runtime-default/

Numbers AWS showed at release

The September 18 announcement and blog gave the following numbers as AWS measurements.

On billing, the blog says the following.

"You pay a higher rate but on far fewer GB-hours, and for most agents the footprint drops more than the rate rises, so the bill goes down."
Source: the ML Blog above

The unit price goes up, but the billed GB-hours drop significantly, so the bill goes down for most agents. I did not verify the billing amount in this article.

The day after release (September 19, 2026), a third-party blog (Classmethod) compared V1 and V2 in the Tokyo Region. The results for three image sizes (46 MB, 335 MB, and 859 MB), measured once each, are below.

Source: https://dev.classmethod.jp/en/articles/amazon-bedrock-agentcore-runtime-v2-tried/

The trend is that V1 gets slower as the image gets larger, while V2 stays almost constant. The values were also close to my own results in this article (about 1.6 to 2.2 s on V2).

What changed with this news

The only change is what happens when you omit the setting while creating a new runtime. Existing runtimes are unchanged.

However, at the time of my verification (November 13, 2026), omitting it gave V1 in my environment (confirmed in the later section "Which version is the default?"). The AWS documentation (How AgentCore Runtime works) also still said "V1 is the default." I could not confirm whether AWS gave any notice about the default change before the announcement.

Conclusion

These are the conclusions within the scope I verified. The conditions were a small container image (about 43.5 MB), an agent that performs a 20-second initialization at startup, and the Tokyo Region.

The following sections show how I checked each item and the results.

AgentCore runtime V1 and V2

This organizes what the official announcement and documentation say. The numbers are the official ones and were not verified in this article.

Sources:

• Announcement: https://aws.amazon.com/about-aws/whats-new/2026/11/new-agentcore-runtime-default/
• Documentation: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-how-it-works.md
• Pricing page: https://aws.amazon.com/bedrock/agentcore/pricing/

The announcement and the official documentation disagree about the default. The announcement says "new runtimes use the next generation by default," but the Platform versions section of the documentation says "V1 is the default." I check this in the next section.

The documentation also includes a caution that comes with the snapshot approach.

"Restoring from a snapshot changes how you structure your agent code."
Source: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html

Verification environment and method

The test agent

It is a small HTTP server written with only the standard library. At startup it performs a 20-second "heavy initialization" and then listens on port 8080. /invocations returns a value fixed at startup and values created for each request.

# Startup processing (expected to be included in the snapshot on V2) time.sleep(INIT_SECONDS) # 20 seconds. Stands in for heavy initialization STARTUP_RANDOM = random.random() STARTUP_UUID = str(uuid.uuid4()) STARTUP_EPOCH = time.time() # Response of /invocations (excerpt) { "startup_uuid": STARTUP_UUID, # value created at startup "startup_epoch": STARTUP_EPOCH, # time of startup "handler_random": random.random(), # Python random inside the handler "handler_uuid": str(uuid.uuid4()), # uuid4 inside the handler "handler_urandom_hex": os.urandom(8).hex(), "pid": os.getpid(), "hostname": socket.gethostname(), } 

/ping does not succeed until the server starts listening, so on V2 the snapshot is expected to be taken once initialization finishes (official description: taken at the first healthy /ping response).

Environment

How I invoked it

I call invoke_agent_runtime with a new runtimeSessionId and record the elapsed time and the response. Each call uses a new session, so every call includes the startup of a new session. To check a running session, I use a fixed session ID.

Which version is the default?

First, I checked the default version, where the official statements disagreed.

Omitting --platform-version in the CLI

aws bedrock-agentcore-control create-agent-runtime \ --agent-runtime-name v_default \ --agent-runtime-artifact "containerConfiguration={containerUri=<ECR image URI>}" \ --role-arn <execution role ARN> \ --network-configuration networkMode=PUBLIC 

After creation, checking with get-agent-runtime --query platformVersion showed V1.

The console create screen

In the Tokyo Region console, once at least one runtime exists, you reach the create screen from "Add more" at the top right of the "Agents" page, then "Host agent". The name differs from "Create Host agent (runtime)" in the documentation.

On the create screen, "Runtime platform version" had V1 preselected, and V2 was labeled "recommended".

This screen had one more notice about V2. For the compute type "Instances", it says "Not available with runtime platform version V2." If you want to use Instances, you cannot choose V2.

This matches "V1 is the default." in the official documentation. The announcement's "the next generation is the default" could not be confirmed in my environment at the time of verification (November 13, 2026). It may be rolling out gradually, but I could not confirm that.

Creation time

I created runtimes in three ways: V1 explicit, V2 explicit, and omitted. The time is the difference between createdAt and lastUpdatedAt from get-agent-runtime.

V2 takes minutes to create because it prepares the snapshot (consistent with "Create and update take minutes." in the documentation).

Wait time for a new session

Comparing V1 and V2

I invoked each 10 times with new sessions. This was measured about 10 minutes after creation.

V2 was stable at around 1.6 to 2 s. Only the first call took 3.68 s.

Invoking three times after waiting 10 minutes showed the same trend.

Why was V1 faster?

Surprisingly, V1 returned faster in this table. The agent takes 20 seconds to initialize, so a new V1 session should take about 20 seconds or more.

Looking at the startup time (startup_epoch), the 10 sessions of v1_explicit and the 3 sessions of v_default, which had never been called, all started about 24 seconds after creation (at the same second each). This means the responses did not come from instances started by the new-session invocation, but from instances that had been started in advance.

On the other hand, for mig_cli (V1), created by the same procedure and checked right after creation, every new-session invocation took 23.7 to 25.7 s. startup_epoch was just before the invocation, so it was really a cold start. It also took 23.7 s right after rolling back from V2 to V1.

I could not identify the condition under which V1 has pre-started instances in this verification. I also found no description of V1 pre-starting in the official documentation.

So for V1 I only state the facts: the wait was about 0.5 s in some cases and about 24 s, including the initialization time, in others. V2's 1.6 to 2.2 s was stable in every situation. The official "P75 from 29.7 s to under 2 s" is a value for a 2 GB image, so it cannot be compared directly with the numbers in this article (a 43.5 MB image).

Effect of snapshots

A snapshot is a saved state of the agent itself, taken per runtime right after its initialization finishes. Values from other runtimes or accounts do not get mixed in. The issue is that multiple sessions restored from the same runtime (for example, invocations from different users) share the values that were created at startup.

If your V1 code implicitly assumes that "each session starts its own dedicated process, so values created at startup differ per session," that assumption breaks on V2. No error is raised and the values are simply the same, so it is easy to miss.

Note that the values compared here are not runtimeSessionId. They are values the test agent created by itself at startup.

On V2, the startup processing is included in the snapshot and carried over to all restored instances. The documentation also says the following.

"The random module is likewise seeded at startup, so restored instances repeat the same sequence."
Source: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-v2-optimize.md

Here are the actual results. I compared the responses of 10 invocations (each with a new session).

What I learned on V2 is as follows.

• Values created at startup (such as startup_uuid) are the same across multiple sessions
• random.random() called inside the handler also gives the same value on the first call in sessions restored from the same snapshot
• uuid.uuid4() and os.urandom() gave a different value every time
• There were two snapshots. Even after waiting more than 10 minutes, sessions were restored from the same two
• From startup_epoch, the snapshot was taken about 97 seconds before READY

As the documentation recommends, random numbers and identifiers must be generated inside the handler using secrets, os.urandom(), or uuid.uuid4(). If your code uses Python's random to generate IDs or tokens, migrating to V2 may produce the same values.

When /ping is not ready in time

On V2 the snapshot is taken at the first healthy /ping response. The documentation says creation fails if the runtime does not become healthy within 120 seconds of startup.

I created a V2 runtime with an image whose startup initialization I changed to 130 seconds.

CREATE_FAILED (about 229 seconds after creation) failureReason: The runtime failed its health check. Ensure your container serves the configured health endpoint. 

If startup initialization exceeds 120 seconds, a V2 runtime cannot be created at all. The time until creation fails is probably 120 seconds plus preparation time, but I did not check the breakdown.

Migrating from V1 to V2 with the CLI

I migrated a V1 runtime (mig_cli) to V2 with update-agent-runtime.

aws bedrock-agentcore-control update-agent-runtime \ --agent-runtime-id <runtime ID> \ --agent-runtime-artifact "containerConfiguration={containerUri=<ECR image URI>}" \ --role-arn <execution role ARN> \ --network-configuration networkMode=PUBLIC \ --platform-version V2 

--agent-runtime-artifact, --role-arn, and --network-configuration also had to be specified on update.

Results

To check the running session, I called a fixed session ID that I started before the update, about every 30 seconds during the update. startup_uuid stayed the same to the end, time.monotonic() kept increasing, and responses took about 0.35 to 0.42 s. It kept running as the same process across the migration.

In other words, when migrating from V1 to V2, sessions that are already running are not affected, and only new sessions switch to V2 at the moment of READY. Invocations did not fail during the update.

The DEFAULT endpoint followed the updated version. For mig_cli, which I updated repeatedly with the CLI, the DEFAULT liveVersion was also 4 when it reached version 4.

Migrating with the Management Console

I could migrate from V1 to V2 in the console as well.

Steps

1. Press the "Update" button at the top right of the runtime detail screen
2. On the "Update runtime" screen, choose V2 under "Runtime platform version"
3. Press "Update runtime"

The name and compute type cannot be changed on the update screen (display only).

Results

Right after pressing it, the following banner was displayed. The status becomes "Updating", and the "Update" and "Test agent" buttons are disabled.

The result was the same as with the CLI.

Where to see V1/V2 in the console

The detail screen header and the list cards do not show V1/V2. It appears as "Runtime platform version" under "Version details" on the "Settings" tab.

On the same screen for a V2 runtime, it shows V2 and also an item "Session capacity: Pay per use" (an item that was not on the V1 screen).

I could not confirm in the official documentation whether "Pay per use" corresponds to the billing mode (consumption). Since this was displayed with resourceConfigurations removed, that is only an inference.

Can you roll back from V2 to V1?

I found no description in the documentation of how to roll back from V2 to V1. I tried the following methods.

The behavior after rolling back was the same as V1 before migration. A new session was a cold start of about 23.7 s, and the fixed session started before migrating to V2 continued as is (responses about 0.36 s).

The documentation says snapshots of versions that are no longer referenced become subject to deletion, and deletion can take up to 8 hours. I did not check what happens to the snapshot after rolling back from V2.

Migrating with CloudFormation

AWS::BedrockAgentCore::Runtime in CloudFormation has a PlatformVersion property (Update requires: No interruption). The allowed values (V1/V2) are not listed in the resource documentation.

Here is an excerpt of the template.

Resources: Runtime: Type: AWS::BedrockAgentCore::Runtime Properties: AgentRuntimeName: cfn_migration AgentRuntimeArtifact: ContainerConfiguration: ContainerUri: !Ref ContainerUri RoleArn: !Ref RoleArn NetworkConfiguration: NetworkMode: PUBLIC PlatformVersion: !Ref PlatformVersion 

With CloudFormation as well, the runtime was updated in place without being replaced. I confirmed in the documentation that the CDK L1 (CfnRuntime) also has platformVersion. I did not verify an actual CDK deployment. I also did not check whether the Terraform provider can specify the equivalent of PlatformVersion.

resourceConfigurations (committed baseline)

V2 has resourceConfigurations for setting a memory baseline. With a baseline set, you are billed at a lower unit price, and at peak you can burst up to 4 times the baseline (per the official documentation).

AWS CLI 2.39.3 and boto3 1.43.91 did not have the resourceConfigurations parameter. I installed a newer boto3 (1.44.2) in a separate virtual environment and tried it.

c.update_agent_runtime( agentRuntimeId=rid, agentRuntimeArtifact={"containerConfiguration": {"containerUri": img}}, roleArn=role, networkConfiguration={"networkMode": "PUBLIC"}, platformVersion="V2", resourceConfigurations=[{"minimumMemoryInMiB": 2048}], ) 

For now, the baseline appears to be configurable only through the API and SDKs (newer versions).

The pricing page says the committed baseline unit price is "launching by October 2026". It could be set through the API, but I do not know whether it is actually reflected in billing because I did not check the bill.

Guidelines for deciding on migration

From the results so far, I summarized guidelines for considering migration to V2 in a table. They are not official statements, but my own view based on the verification results of this article.

The migration procedure itself is just an update, running sessions are not affected, and you can roll back. It is a low-risk operation, so a sensible flow is to first check V2 behavior on a test runtime and then proceed.

How to verify this yourself

I did the verification in the following order. Please adapt the command arguments to your own environment.

1. Create an ECR repository, build the test image for linux/arm64, and push it
2. Create an execution role (trust policy for bedrock-agentcore.amazonaws.com)
3. Create with create-agent-runtime in three ways: --platform-version V1, V2, and omitted. Check status and platformVersion with get-agent-runtime
4. Call invoke_agent_runtime several times with new runtimeSessionId values and compare the elapsed time and responses (startup values, values in the handler)
5. Create another runtime as V1, and while calling a running session (fixed session ID), migrate it to V2 with update-agent-runtime. Record status, platformVersion, and duration
6. Try the same on the console update screen
7. Check whether you can roll back with --platform-version V1
Source：https://dev.to/aws-builders/aws-migrating-agentcore-runtime-from-v1-to-v2-agentcore-7fn
My favorites