Session Isolation & the Security Boundary

Agents are a uniquely hostile thing to multi-tenant. They are non-deterministic, they hold stateful reasoning context across turns, and they perform privileged tool operations on a user's behalf — reading files, calling APIs, running code. Sharing a process between two users' sessions would be a data-leak waiting to happen.

AgentCore Runtime's answer is the strongest isolation primitive it can offer: every user session gets its own dedicated microVM with isolated compute, memory, and filesystem. AWS's developer guide calls it a "dedicated microVM"; the runtime GA blog and surrounding ecosystem write-ups describe it specifically as a Firecracker microVM (treat the exact hypervisor name as ecosystem-sourced rather than a devguide guarantee).

The second half of the guarantee is the teardown: on session termination the microVM is destroyed and its memory sanitized, so there is no cross-session contamination. Session A cannot read session B's in-memory secrets, scratch files, or conversation — because session B never shared a kernel, a heap, or a disk with it in the first place.

This is the architectural difference from a classic stateless FaaS. AgentCore provisions the microVM per session and keeps it alive across many invocations (up to 8 hours), rather than spinning an anonymous worker per request. The isolation unit is the session, not the request.

A session moves through three observable states:

• Active — currently processing an invoke, or running tracked background tasks.
• Idle — provisioned and holding context, but not doing work right now (waiting for the next turn).
• Stopped / Terminated — the microVM has been torn down and its memory sanitized.

Four things move a session into the terminated state:

The two timeouts are configurable through LifecycleConfiguration on the agent runtime — idleRuntimeSessionTimeout for the idle window and maxLifetime for the ceiling (both [VOLATILE] defaults — verify on the live quotas page):

{
  "lifecycleConfiguration": {
    "idleRuntimeSessionTimeout": 900,
    "maxLifetime": 28800
  }
}

A subtle but important rule: a new invoke with the same runtimeSessionId after a stop provisions a fresh microVM with a new ≤8-hour lifecycle. The session ID itself "remains valid until the AgentCore Runtime ARN is deleted" — so reusing an ID after termination is allowed, it just doesn't resurrect the old microVM's in-memory state.

Because the microVM is destroyed on termination, anything you keep in memory or on the local disk lives only for that microVM's lifecycle. When the session stops — idle timeout, max lifetime, explicit stop, or crash — that state is gone and sanitized. This is the single most common mental-model mistake: treating a session's RAM or /tmp as if it were a database.

There are two first-class ways to make state survive a teardown:

1. Session storage — a persistent mount path that survives stop/resume of the same session ID, for filesystem state your agent reads and writes (scratch files, downloaded artifacts, working directories). It is capped at 1 GB per session ([VOLATILE] — verify on the limits page).
2. AgentCore Memory — the managed service for durable conversational state (short-term turns and long-term extracted facts), independent of any one microVM. This is what you reach for when a user comes back tomorrow and expects the agent to remember them.

A useful rule of thumb:

If you find yourself writing "save to /tmp and hope it's there next turn," stop — that only works within a live microVM and breaks the moment the session is recycled.

The session ID does double duty. It is the key that ties related invocations into one conversation, and it is what routes you back to the same warm microVM — what AWS calls microVM "stickiness" or affinity.

The rules:

• Generate one unique ID per user/conversation. It must be at least 33 characters (commonly cited; confirm against the live API reference). A UUID is 36 characters, so a plain uuid4() satisfies the minimum.
• Reuse the same ID for every invoke in that conversation. This keeps your reasoning context and is what pins you to the already-provisioned microVM.
• Echo the returned ID. The client must capture the session ID returned in the response and send it back on the next call. If you let each request fall back to a new ID, every request may land on a fresh microVM — paying cold-start latency each time and losing affinity.

From boto3, you supply runtimeSessionId explicitly on the data-plane invoke_agent_runtime call:

import json, uuid, boto3

client = boto3.client("bedrock-agentcore")          # data plane
session_id = str(uuid.uuid4())                        # 36 chars >= 33 minimum

resp = client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-XXXX",
    runtimeSessionId=session_id,                      # REUSE this for the whole conversation
    payload=json.dumps({"prompt": "Tell me a joke"}).encode(),
    qualifier="DEFAULT",
)
print(json.loads("".join(c.decode("utf-8") for c in resp.get("response", []))))

# Next turn in the same conversation -> same session_id -> same warm microVM
resp2 = client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-XXXX",
    runtimeSessionId=session_id,                      # same ID, not a new uuid4()
    payload=json.dumps({"prompt": "Now make it about databases"}).encode(),
    qualifier="DEFAULT",
)

Inside the runtime, your code can read the active session ID from the request context — e.g. via context.session_id on the optional RequestContext argument — which is handy for keying session storage paths or correlating logs.

Here is the boundary that trips up every team building their first multi-user agent: AgentCore does not maintain any relationship between users and session IDs. The devguide is explicit — "your client backend should maintain the relationship between users and their session IDs."

A session ID to AWS is just an opaque routing/affinity key. It does not know that session a1b2... belongs to Alice, that Alice may have three concurrent conversations, or that your product limits each user to five active sessions. All of that is yours to own. Concretely, your backend is responsible for:

• The user→session mapping — storing which session ID(s) belong to which authenticated user, in your own datastore.
• Per-user session caps — deciding and enforcing how many concurrent sessions a user may hold (AgentCore only enforces an account-level active session workloads quota, not per-user limits).
• Authorization — verifying that the caller actually owns a session ID before forwarding their invoke with it. Nothing stops a client from sending someone else's ID; you must reject that.

A minimal backend mapping pattern:

import uuid

# Pseudocode: your service, your datastore, your auth
MAX_SESSIONS_PER_USER = 5

def get_or_create_session(user_id: str, conversation_id: str) -> str:
    record = sessions_table.get(user_id, conversation_id)
    if record:
        return record["runtime_session_id"]            # reuse -> context + affinity

    active = sessions_table.count_active(user_id)
    if active >= MAX_SESSIONS_PER_USER:
        raise PermissionError("Per-user session cap reached")

    session_id = str(uuid.uuid4())                       # >= 33 chars
    sessions_table.put(user_id, conversation_id, session_id)
    return session_id

def authorize(user_id: str, session_id: str) -> None:
    if not sessions_table.owns(user_id, session_id):
        raise PermissionError("Session does not belong to this user")

The microVM isolation guarantees that sessions can't leak into each other. Owning the mapping guarantees that the right user reaches the right session in the first place — and that is squarely your responsibility, not AWS's.

How the session ID travels on the wire depends on which protocol your runtime declares. The data-plane API exposes runtimeSessionId as a parameter, but at the HTTP layer it maps to a protocol-specific header — and the header name is not the same for MCP.

If you call an HTTP-protocol runtime with a raw HTTPS request (which you must do when the agent uses OAuth inbound auth, since the AWS SDK can't sign those), you set the session header yourself:

curl -X POST "$AGENT_INVOKE_URL" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: 9f8c5b6a-0d1e-4f23-8a77-1c2d3e4f5a6b" \
  -d '{"prompt": "What is the weather?"}'

MCP is the special case. When you host an MCP server inside Runtime (port 8000, POST /mcp, streamable-http), the platform injects and returns Mcp-Session-Id. Your server must accept the platform-generated ID and must not reject it — a common failure in stateless MCP mode is a server that tries to mint or validate its own session ID and rejects the platform's. Default MCP servers to stateless_http=True and let the platform own the session header:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP(host="0.0.0.0", stateless_http=True)   # accept the platform Mcp-Session-Id

@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b

if __name__ == "__main__":
    mcp.run(transport="streamable-http")              # served at /mcp on port 8000