How to delete old runtime versions in agentcore (or at lease cease using them)?

When you update an AgentCore Runtime, the system creates a new immutable version rather than replacing the old one. This is by design - the DEFAULT endpoint automatically points to the latest version of your AgentCore Runtime, but existing sessions will continue using the version they started with until they complete.

The versioning approach allows for controlled transitions between versions. While the DEFAULT endpoint automatically updates to point to the new version when you update your AgentCore Runtime, any active sessions that were already running will continue using the version they were initialized with until those sessions complete.

If you want to ensure all traffic immediately uses the new version, you would need to terminate any existing sessions. However, there isn't a direct CLI command to delete old versions or forcibly terminate sessions using those versions.

This versioning behavior is intentional as it provides stability for in-progress operations. New sessions will automatically use the latest version (via the DEFAULT endpoint), while allowing existing sessions to complete their work on the version they started with, preventing disruption to ongoing processes.

For updating an Agent on Bedrock AgentCore Runtime, you can use the update_agent_runtime method from the boto3 client for bedrock-agentcore-control, which will create a new version and update the DEFAULT endpoint to point to it. New sessions will then use this latest version.
Sources
AgentCore Runtime versioning and endpoints - Amazon Bedrock AgentCore
Updating an Agent to a new version when executing on Bedrock Agentcore Runtime | AWS re:Post

When you update an AgentCore Runtime, Bedrock creates a new immutable runtime version rather than replacing the existing one. This is intentional behavior, and multiple versions are designed to coexist so that you can run them in parallel or switch between them by pointing an endpoint to the version you want.

The DEFAULT endpoint automatically re-targets itself to the latest runtime version whenever you deploy an update. This ensures that new traffic is directed toward the newest version without manual intervention.

The older versions continue running, but only in the sense that they remain available. Bedrock currently does not provide an API or CLI operation to delete old runtime versions. There is also no direct mechanism to forcibly terminate existing sessions bound to an older runtime version.

There is no official documentation stating that active sessions are guaranteed to remain pinned to their original runtime version, but it is reasonable to expect that any in-flight request would continue on the version it started on to avoid disruption. For long-lived sessions, the recommended approach is for the application to handle any needed migration.

So how do you stop old sessions from being used?

There is no API today to explicitly end or terminate sessions. The correct pattern is to rotate to new sessions at the application level whenever the endpoint begins pointing to a new runtime version.

You can detect which version an endpoint is currently using by calling:

• GetAgentRuntimeEndpoint API • Or its CLI equivalent: aws bedrock-agentcore-control get-agent-runtime-endpoint

-https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_GetAgentRuntimeEndpoint.html -https://docs.aws.amazon.com/cli/latest/reference/bedrock-agentcore-control/get-agent-runtime-endpoint.html

Both will return a targetVersion field, which tells you exactly which runtime version the endpoint is currently routing to.

Recommended approach (release and rollback safe)

Your application should:

• Deploy a new AgentCore runtime version.
• The DEFAULT endpoint automatically updates to point at the new version.
• Your application calls GetAgentRuntimeEndpoint to check the endpoint’s targetVersion.
• If targetVersion has changed (either upgraded or rolled back): -Create new sessions for all users instead of reusing old session IDs. -Allow existing requests/sessions to finish naturally. -Older sessions will simply fade out as they expire.

This same logic applies during rollbacks: if the endpoint’s targetVersion moves down (to a prior version), your application should again detect the change and generate new sessions accordingly.

Why this works

• You don’t need to forcibly terminate anything.
• New traffic immediately uses the new runtime version.
• Old versions incur no cost unless actively invoked.
• Your application maintains consistent behavior across releases and rollbacks.

Summary

• Old AgentCore runtime versions cannot be deleted.
• DEFAULT endpoint always points to the newest runtime version.
• No API/CLI exists today to terminate sessions.
• Applications should rotate to new sessions when targetVersion changes.
• Use GetAgentRuntimeEndpoint to detect version changes programmatically.

This pattern ensures a clean migration path for both upgrades and rollbacks without breaking in-progress work.

Sources: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agent-runtime-versioning.html https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-session-characteristics.html -https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_GetAgentRuntimeEndpoint.html -https://docs.aws.amazon.com/cli/latest/reference/bedrock-agentcore-control/get-agent-runtime-endpoint.html