Optimize your agent for Amazon Bedrock AgentCore Runtime V2
Amazon Bedrock AgentCore Runtime V2 starts your agent by restoring a snapshot. This changes how you structure your agent code. Work that your agent does at startup is captured in the snapshot and shared by every restored instance. Produce any value that must differ between requests, or that can expire, in your request handler instead. This topic describes how to structure your agent around startup work and per-request work so that it stays correct after each restore. For an overview of platform version V2, see Platform versions.
Your agent has two execution contexts:
- Startup
-
Code that runs once as your process starts, before AgentCore Runtime takes the snapshot. AgentCore Runtime captures this code in the snapshot, and every instance inherits its results.
- Request handling
-
The code in your
/invocationshandler. This code runs on every request on every instance.
Use one rule to decide where code belongs. Compute a value at startup if it stays the same for the life of the snapshot. Compute it in your handler if it varies per request or can expire. AgentCore Runtime takes one snapshot per agent version and uses it until you create or update the agent, so the life of the snapshot is the life of that version.
Initialize once at startup
Do expensive, reusable work as your process starts, before the snapshot. For example, import dependencies, load model weights, or read static configuration from your deployment bundle. With the AgentCore SDK, do this work at module scope, before you call app.run(). Your agent does not listen on port 8080 until app.run() runs, so no /ping can succeed and no snapshot can be taken until your startup work finishes. The snapshot captures a fully initialized agent by construction, and you do not need to gate /ping. Complete initialization within 120 seconds of startup. If your agent does not become healthy in time, the runtime fails its health check. For more information about the /ping and /invocations endpoints, see Understand the AgentCore Runtime service contract.
import json, pathlib from bedrock_agentcore.runtime import BedrockAgentCoreApp # Runs once at import, before app.run() starts the server and before the # snapshot. Every restored instance inherits these objects. MODEL = load_model_weights() SETTINGS = json.loads((pathlib.Path(__file__).parent / "agent.json").read_text()) app = BedrockAgentCoreApp() @app.entrypoint def invoke(payload): # Per-request work runs here on every instance. ... app.run() # starts listening on 8080; the snapshot is taken after this
If your agent runs its own HTTP server instead of the AgentCore SDK, the snapshot must capture a fully initialized agent. You can do this in one of two ways:
-
Report a healthy status from
/pingonly after initialization completes. -
Report a healthy status as soon as your server starts, and do the initialization in a lifecycle hook’s
memorycall. Sessions start with what that call loads. For more information, see Prepare memory and disk with a lifecycle hook.
Read only data at startup that is the same for every instance and does not expire. Handle time-sensitive values, such as short-lived credentials, in your handler.
Do not compute anything at startup that you change without redeploying. For example, a tool catalog fetched from AgentCore Gateway looks like an ideal startup value because it is slow and expensive to load, but caching it at startup freezes your agent’s tool inventory at the time of the snapshot.
Prepare memory and disk with a lifecycle hook
While AgentCore Runtime prepares your agent, a build warmup lifecycle hook makes two calls to your hook, first memory and then disk, and tells your handler which call it is. For example, with an HTTP action, both calls go to the path and port that you configure, and the X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type header identifies the call. In the memory call, run initialization that needs your server to be running. In the disk call, read the files that your agent reads when a session starts, so that new sessions can use them faster. This helps agents whose sessions start by reading large files, such as a large binary, a heavy set of Python packages, or a headless browser.
| Warmup type | What it prepares | Use it for |
|---|---|---|
|
|
Memory that every session starts with |
Initialization that needs your server to run, or that you want to do after |
|
|
The files that a session reads when it starts |
Reading those files, so that new sessions can use them faster |
The memory and disk calls share 120 seconds, and the memory call runs first. Do the expensive work in the memory call, and keep the disk call to the files that one session reads when it starts. For how to configure the hook and write its handler, see Configure lifecycle hooks for AgentCore Runtime.
Keep per-request state fresh
The snapshot is captured once and shared by every restored instance, so any value that your agent generates at startup is identical across instances and fixed at the time of the snapshot. Handle values that the snapshot cannot carry in your /invocations handler. The following table describes values to compute in your handler instead of at startup.
| To do this | Do it in the handler | Reason |
|---|---|---|
|
Generate random values, identifiers, or tokens |
Call |
|
|
Read the current time |
Compute it for each request |
A timestamp captured at startup is fixed at the time of the snapshot. |
|
Measure elapsed time |
Take the reference timestamp in your handler |
|
|
Use credentials or tokens |
Refresh them when they expire |
Credentials loaded at startup can expire before an instance starts. |
|
Identify the instance or worker |
Generate an id per request; do not derive it from the host |
Every restored instance reports the same hostname ( |
Build reusable clients at startup, and compute per-request values on each call.
import os, time # Build reusable clients at startup, before the snapshot. Exercise them here too # (for example, with a warm-up call) so the setup the client caches — endpoint and # credential resolution, connection pool — is captured in the snapshot. client = build_client() warm_up(client) @app.entrypoint def invoke(payload): creds = get_credentials() # refreshed when expired, not read at startup request_id = os.urandom(16).hex() # unique per request now = time.time() # current time, not snapshot time # Handle the request.
Use snapshot-safe cryptographic libraries
When AgentCore Runtime restores instances from a snapshot, every instance created from that snapshot starts with an identical copy of the memory captured at snapshot time. This includes the internal state of random number generators inside cryptographic libraries, and any keys, tokens, or identifiers your agent created during initialization. Unless that state is refreshed after the restore, instances can produce the same "random" values.
Current limitation
On AgentCore Runtime, snapshot-safe builds of cryptographic libraries don’t reseed after a restore. This applies to both direct code deployments and container deployments.
Workarounds
-
Generate secrets, keys, tokens, and session identifiers while handling a request, not when your agent starts. This avoids using any values created before AgentCore Runtime takes the snapshot in each instance restored from that snapshot.
-
Even while handling a request, get random values directly from the operating system, for example Python’s
secretsoros.urandom, Go’scrypto/rand, or reading/dev/urandom. Don’t use random values from a cryptographic library such as OpenSSL, because they can repeat across instances. -
In Node.js, the
cryptomodule uses OpenSSL. This includescrypto.randomBytes(),crypto.randomUUID()(also withdisableEntropyCache: true),crypto.randomInt(),crypto.getRandomValues(), and packages built on them, such asuuid. Values from these functions can repeat across instances, even when you call them in your handler. To get unique values in Node.js, read bytes from/dev/urandom.
Networking
- Build clients at startup and expect a transparent reconnect
-
The socket you open at startup does not survive a restore, but the setup your client library caches around it — service-model parsing, endpoint resolution, credential resolution, and the connection pool — does. Construct and exercise your clients at startup, and expect the first call after a restore to re-establish the connection transparently.
- Do not use the hostname or PID as a unique instance identifier
-
Every restored instance starts from the same snapshot and reports the same hostname and process ID. Generate a unique identifier in each request.
- Avoid binding to a fixed source port
-
After a restore, the connection held at snapshot time is re-established, and a fixed source port can collide with that replacement within the instance. Restored instances are separate microVMs with their own network namespaces, so the conflict is within an instance, not across them.
Cross-account metrics and quotas
For a cross-account invocation, where a principal in one account invokes an agent runtime owned by another account through a resource-based policy, the CloudWatch metrics and the rate-limit quota usage for the invocation are attributed to the resource owner’s account. The resource owner is the account that owns the agent runtime.
You can also view the metrics that count toward your quota in the Service Quotas