Skip to content
By using AWS re:Post, you agree to the AWS re:Post Terms of Use
AWS re:Postre:Post
About re:Post

Amazon Bedrock AgentCore Runtime: pre-monitor maxLifetime so long-running agents checkpoint before the restart, resume cleanly on V2 and after deploys, and plan cold starts per Region

16 minute read
Content level: Advanced
0

AgentCore Runtime runs each session in its own isolated microVM, lets the session continue on a new microVM, and gives you configurable lifecycles, persistent session storage and fast V2 snapshot cold starts.his article connects those capabilities across the docs so your agents checkpoint before maxLifetime, resume cleanly on V2 and after deploys, and follow a cold-start plan that fits your Region, with every step linked to AWS documentation.

By Kiran Khambete and Krish Balaraman

AgentCore session lifecycle: two gaps the docs don't connect

Two details only become clear when you read several pages together, so they are worth knowing up front: AgentCore gives your code no advance notice before maxLifetime ends a microVM, and the Regional session quota and V2's Region list do not line up. The natural checkpoint fix for the first also needs three adjustments, which Gap 1 walks through.

Start here: what AWS already documents

Read those first. They are each complete and correct on their own terms. This article covers the two places where following one of them runs into something stated only on a different page, or into something no page states at all.

Sessions and microVMs are different objects

Both gaps below depend on this distinction. A session is logical and keyed by your runtimeSessionId. A microVM is the environment that serves it. When idleRuntimeSessionTimeout fires, the quotas page says "the execution environment is terminated and a new one is created for the session." The session survives. You lose the warm environment, so the next call to that session ID pays a cold start.

maxLifetime works the same way. The lifecycle page calls it the "Maximum lifetime for the instance" and adds: "The session itself can persist beyond this with a new instance provisioned."

Neither timeout ends the conversation. Both schedule a cold start inside it.

The Use isolated sessions page states the split directly: "Sessions last up to 8 hours for each lifecycle on microVMs, or up to 14 days on Instances," and "The session itself remains valid until the AgentCore Runtime ARN is deleted." When the How AgentCore Runtime works page says a session "can persist for up to 8 hours of total runtime," read that as one lifecycle, not the session.

Gap 1: no advance notice before maxLifetime

maxLifetime ends the instance and a new one is provisioned for the session. With the 8-hour default, a long session gets a forced cold start at hour 8. Nothing went wrong and no request was slow. The timer "starts when the microVM is first created and cannot be reset." Activity does not postpone it. Even a session being invoked continuously still hits this ceiling.

No AWS-documented mechanism signals an approaching maxLifetime termination. The /ping health contract reports your agent's status to AgentCore; it is not a channel for AgentCore to warn your agent. No CloudWatch metric or event fires before the timer expires. The lifecycle page says termination "can last up to 15 seconds due to logging and other process completion," but no page describes a shutdown signal your code can handle, so do not build on one. This absence holds across the lifecycle settings page, the quotas page, the async/long-running-agents page, and all four protocol contracts (HTTP, MCP, A2A, AG-UI).

AWS does cover the general pattern. AGENTCOST03-BP03 recommends "custom checkpoint logic that writes state snapshots to the persistent filesystem," and the filesystem page says that when a session stops, "Any data not yet persisted is flushed to durable storage during graceful shutdown." Files you have already written to session storage are safe. What is at risk at maxLifetime is in-memory state and work in progress. Three details, each on a different page, decide whether a proactive checkpoint actually works.

The timer belongs to the microVM, not the session

When a stopped session is invoked again, the Use isolated sessions page says a new compute is provisioned "with the same lifecycle configuration (i.e. idleRuntimeSessionTimeout and maxLifetime that can be up to another 8 hours)." Each restart gets a fresh timer. A start time written to storage on the first invocation and read back later belongs to the previous microVM, so every remaining-time calculation after the first restart is wrong.

On V2, a startup timestamp is the snapshot's timestamp

The natural place to record "when did this environment start" is startup code. On V2 that is wrong. The V2 optimization page says "A timestamp captured at startup is fixed at the time of the snapshot," and "time.monotonic() does not advance across a restore, so a duration measured from a startup reference is wrong without looking wrong." A V2 agent that computes elapsed time from a startup reference measures from snapshot creation, which can be days earlier than the microVM it is running on. Take the reference inside the request handler instead.

A deploy can erase the checkpoint

Managed session storage is in Preview, runs on microVM runtimes only, and is off until you add it to filesystemConfigurations. Without it, the Use isolated sessions page says data "written to disk persists only for the compute lifecycle." Its reset rules matter here. The filesystem page says session data is reset when "The agent runtime version is updated. Invoking a session after a version update provisions a fresh file system."

Combine that with the lifecycle page's tip that "existing sessions will continue using the previous version until they terminate and new sessions are created." A session that started before a deploy keeps running the old version. When maxLifetime ends its microVM and the session resumes, it comes back on the new version, with an empty session-storage directory. A checkpoint written there just before the deadline is gone.

Instances behave differently. Capacity provider volumes are "retained across these stops, including when a session reaches its maximum lifetime," and are deleted only when you delete the session or the capacity provider.

The approach

Figure 1 shows how the pieces fit together. The numbered steps below map to it.

PRE-MONITOR BEFORE maxLifetime   ->   RECOVER ON THE NEXT INVOKE
==================================================================
[code] = your agent code   [runtime] = AgentCore   [store] = storage

(1) [runtime] InvokeAgentRuntime  -  runtimeSessionId = S
+----------------------------------------------------------------+
| (2) [runtime] microVM #1 created; maxLifetime timer starts     |
|     activity cannot reset it                                   |
+----------------------------------------------------------------+
    |
    v  first request
+----------------------------------------------------------------+
| (3) [code] T0 = time.time() inside the request handler         |
|     start a background watchdog thread                         |
|     NOT at startup (V2 = snapshot time), NOT time.monotonic()  |
+----------------------------------------------------------------+
    |
    v
+----------------------------------------------------------------+
| (4) [code] watchdog: remaining = maxLifetime - margin          |
|                                 - (now - T0)                   |
|     remaining > checkpoint budget?  -> sleep, check again      |
+----------------------------------------------------------------+
    |
    v  remaining <= checkpoint budget
+----------------------------------------------------------------+
| (5) [code] PROACTIVE CHECKPOINT                                |
|     serialize in-memory state; stop starting long work         |
|     >> [store] session storage (microVM) / volume (Instances)  |
|     >> [store] also Memory/S3/EFS if you deploy mid-session    |
+----------------------------------------------------------------+
    |
    v
+----------------------------------------------------------------+
| (6) [runtime] maxLifetime reached  -  NO advance signal        |
|     microVM #1 terminated (up to 15 s tail)                    |
|     without (5): in-memory state lost, task restarts           |
+----------------------------------------------------------------+
    |
    v  next invoke, same runtimeSessionId = S
+----------------------------------------------------------------+
| (7) [runtime] microVM #2: fresh timer, current runtime version |
|     V2: restored from the snapshot                             |
|     version changed? -> session storage is EMPTY (microVM)     |
+----------------------------------------------------------------+
    |
    v
+----------------------------------------------------------------+
| (8) [code] RESTORE AND RESUME                                  |
|     read the checkpoint (durable store if storage was reset)   |
|     first request records a new T0  -> back to (3)             |
+----------------------------------------------------------------+

NOTE: the watchdog is the only warning you get. AgentCore sends
nothing before (6), and the timer restarts on every new microVM.

Figure 1 — pre-monitoring before maxLifetime, and recovery. AgentCore starts the maxLifetime timer when it creates the microVM (2) and gives your code no warning before it ends it (6). The watchdog your code starts on its first request (3, 4) checkpoints in-memory state before the deadline (5). The next invocation of the same session lands on a new microVM with a fresh timer and the current runtime version (7), and the agent restores the checkpoint and resumes (8). On microVMs, session storage is reset when the runtime version changes, so state that must survive a deploy also goes to a durable store.

  1. Configure persistent storage first: managed session storage on microVMs, or a capacity provider volume on Instances. Without either, nothing on disk survives the restart.
  2. Record the microVM's start reference inside your request handler, the first time this process serves a request. Use wall-clock time (time.time()) held in process memory. Do not take it at startup (snapshot time on V2), do not use time.monotonic(), and do not read it back from storage.
  3. Allow for the error in that reference. The first request arrives after the microVM is created, so elapsed time is undercounted by roughly the cold-start duration. Subtract a margin.
  4. Compute remaining time on a background timer, not only when a request arrives. A per-request check never runs if no request arrives near the deadline, and an agent doing background work (reporting HealthyBusy) may receive none.
  5. Size the threshold on how long your checkpoint write takes, plus the margin from step 3. The 15-second termination tail comes after the deadline, so it gives you no time before it.
  6. Below the threshold, serialize in-memory state to the mount and stop starting work that cannot finish before the deadline.
  7. On restart, read the checkpoint first. If you deploy while microVM sessions are running, keep state you cannot afford to lose in a store that survives a version update, such as AgentCore Memory, Amazon S3, or a bring-your-own Amazon EFS or S3 Files mount.

A minimal sketch of steps 2 to 6, for an agent built with the AgentCore Python SDK. It is illustrative and untested; adapt it to your framework.

import threading, time
from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()

MAX_LIFETIME = 28800       # match your runtime's maxLifetime, in seconds
START_MARGIN = 120         # first request arrives after the microVM is created
CHECKPOINT_BUDGET = 60     # seconds your checkpoint write needs

_start = None
_lock = threading.Lock()

def _watch():
    while True:
        remaining = MAX_LIFETIME - START_MARGIN - (time.time() - _start)
        if remaining <= CHECKPOINT_BUDGET:
            checkpoint_in_memory_state()   # your serializer; writes under /mnt/...
            return
        time.sleep(min(30, max(1, remaining - CHECKPOINT_BUDGET)))

@app.entrypoint
def invoke(payload):
    global _start
    with _lock:
        if _start is None:
            _start = time.time()   # taken in the handler: correct on V1 and V2
            threading.Thread(target=_watch, daemon=True).start()
    ...   # your agent logic

app.run()

Gap 2: Regional quota and platform version V2 do not line up

The default for active session workloads is 5,000 per account in US East (N. Virginia) and US West (Oregon). Every other Region gets 2,500. The quota is adjustable through Service Quotas and is set per Region. Separately, platform version V2, which starts your agent from a snapshot instead of initializing on every cold start, is available only in US East (N. Virginia), US East (Ohio), US West (Oregon), Europe (Ireland), and Asia Pacific (Tokyo).

Neither page states the consequence of combining them. A workload pinned to a Region for data residency, outside us-east-1 and us-west-2, starts at the 2,500 quota. Three V2 Regions (US East (Ohio), Europe (Ireland), and Asia Pacific (Tokyo)) are in that 2,500 tier. Every other Region has neither V2 nor the 5,000 default. There, snapshot restore is not available, and the main remaining cold-start lever is keeping sessions warm with session affinity and a longer idle timeout. The initialization work in AGENTCOST06-BP03 (lazy context loading, caching on persistent storage) still applies, because it does not depend on V2.

Warm sessions are cheap in compute but not in quota. AGENTCOST06-BP03 says the Idle state keeps readiness "without compute charges." The HTTP protocol contract warns that a /ping timestamp that advances on every ping "prevents the idle session timeout from ever firing — sessions then persist until MaxLifetime and can exhaust your session quota." Sessions that have not yet timed out hold quota. In a Region with neither V2 nor the 5,000 default, the warm-session lever spends the smaller quota tier, with no snapshot-restore fallback.

Check your Region's actual quota in Service Quotas, and check V2's Region list, before you size a cold-start strategy. A quota increase is not an incident fix. Request it before launch, not after a quota error.

To track usage, alarm on ActiveSessionCount in the AWS/Bedrock-AgentCore namespace, filtered to Service = AgentCore.Runtime. The metrics page says it helps you "understand your session quota consumption." Set the threshold against your Region's actual quota, not against 5,000.

What platform version V2 changes

V2 targets cold-start latency directly; the timeouts only change how often you pay it. AgentCore "prepares your environment once and takes a snapshot of it, then restores that snapshot for each new instance." Cold-start latency stays "consistent regardless of concurrency or image size," which matters most for large container images. V2 also reclaims memory as the agent releases it.

V2 is not a drop-in switch. The documentation says: "Restoring from a snapshot changes how you structure your agent code." V1 is the default.

Check these before you plan on V2:

  1. Availability. V2 runs only in the five Regions listed above. The documented setup uses the microVMs compute type.
  2. Infrastructure as code. "AWS CloudFormation and the AWS CDK do not currently support setting platformVersion." You set it through the console, CLI, or SDK.
  3. Deployment time. Create and update "run for several minutes before the runtime reaches READY." An update or delete before a terminal state returns ConflictException, so pipelines must poll.
  4. Health checks. The snapshot is taken on the first healthy /ping, which must arrive within 120 seconds of startup. Report healthy only after initialization finishes.
  5. Environment variables. V2 caps their total size at 1.5 KB for direct code deployments and 2.5 KB for containers. V1 allows 4 KB.

If you run V1 with large images and V2 is available in your Region, evaluate it before tuning timeouts.

For regulated workloads

Gap 2 above is the direct consequence for a workload that does not choose its own Region. Three more considerations:

Change control that requires CloudFormation or CDK blocks V2 today. Either run V2 as a recorded exception or wait for IaC support. Do not set it by hand and let templates drift.

If you keep sessions warm to work around a missing V2 or a tight quota, note that "if you update your agent runtime with new code, existing sessions will continue using the previous version until they terminate and new sessions are created" (lifecycle page). A rollback reaches active users only as their environments recycle. That takes up to maxLifetime: 8 hours by default, or days on the Instances compute type. Runbooks and change records should state the expected convergence time, and the session-rotation or StopRuntimeSession step that forces it if a fix must land faster.

On microVM runtimes, every release also resets managed session storage for each session it reaches (Gap 1). A change record for an agent that keeps state in session storage should state what that state is, where it is kept if it must survive the release, and that each session resumes with an empty directory on its first invocation after the update.

Checklist

  1. Set both idleRuntimeSessionTimeout and maxLifetime explicitly; do not rely on the default-resolution rules.
  2. Configure persistent storage before you rely on any checkpoint: managed session storage (Preview) on microVMs, or a capacity provider volume on Instances.
  3. Track maxLifetime per microVM, not per session. Take the reference timestamp inside the request handler and compute remaining time on a background timer. Never use a startup timestamp or time.monotonic() on V2. No AWS mechanism warns you in advance.
  4. Checkpoint in-memory state before the deadline. On microVMs, keep state that must survive a deploy outside session storage.
  5. Read your Region's active session workloads quota in Service Quotas. Do not assume 5,000.
  6. Check whether platform version V2 is available in your Region before relying on it as your cold-start fix.
  7. If your Region has neither the 5,000 quota tier nor V2, plan on warm sessions plus initialization optimization, and request a quota increase before launch.
  8. Alarm on ActiveSessionCount, filtered to AgentCore.Runtime, against your Region's actual quota.
  9. Plan how a release reaches active sessions: session rotation or StopRuntimeSession. Record the convergence time, and the session-storage reset, in change records.
  10. Evaluate V2 before tuning timeouts, after checking Region, IaC, and environment-variable limits.

Limitations

  • Idle sessions and the quota. The HTTP protocol contract implies that sessions which have not timed out consume quota, but no quota page states a rule for the Idle state. Verify in your account.
  • Quota values change. Every number here is a documented default on the verification date. Read your own values in Service Quotas.
  • Managed session storage is in Preview. Its reset rules, limits, and Region availability may change; check them before you design around it.
  • The code sketch is illustrative and has not been run on AgentCore Runtime. The start reference is approximate by about one cold start, which is why the sketch subtracts a margin.
  • Scope. This covers AgentCore Runtime only, with agents hosted on AgentCore Runtime. Agents that run elsewhere and call AgentCore have a different cold-start and credential model and are out of scope.
  • V2 behavior comes from documentation, not measurement. Benchmark your own agent before and after.
  • Quota scope across services. Code Interpreter and Browser each have their own "Concurrent active sessions per account" quota on the quotas page, but ActiveSessionCount reports all three workload types. Filter to AgentCore.Runtime when you alarm against the Runtime quota.

References

No comments

Relevant content