AgentCore:Session mechanisms and session isolation

This topic primarily describes high-code agents and helps you design session IDs and history management for service calls. Differences for managed Harnesses and other agent types are explained in the relevant sections. Before you start, deploy a high-code agent by following Deploy and use a high-code agent. Configure the session ID method when you create the agent, because AgentCore identifies sessions by an HTTP header and the name of the header that carries the session ID is part of the agent configuration. For details, see Passing a session ID. Obtain the endpoint URL and the authentication method from the call instructions for the target endpoint; if API key authentication is used, configure the corresponding header and secret. Confirm that the instance capacity settings (Number of instances, Maximum Sessions per instance, and Session TTL) are in place for your agent. For details, see Sessions and instance capacity.

Sessions and session IDs

A session groups requests that belong to the same conversation or interaction. For example, an end user first submits "Analyze this report" and then asks "Summarize the conclusions in three points." The two requests can use the same session ID. When the end user starts a separate conversation, use a new session ID.

This topic distinguishes between two roles: the end user who interacts with the agent and the caller (business application) that integrates the agent. The caller generates and maintains session IDs. Throughout an integration, the caller completes five tasks. Configure the session ID method when you create the agent, as described in Passing a session ID. Generate a session ID for each conversation, reuse it within the conversation, and use a new value for a new conversation. Send the session header with every request and carry the session fields in the format of the selected protocol, as described in Request structure and session fields. Provide conversation history and business state in requests as required by your application, as described in Ownership of history and state. Validate routing, isolation, and recovery by using the methods in Integration validation. The session mechanism involves the following concepts:

Ownership of history and state

A session ID identifies a session; it is not the conversation history itself. Assigning two requests to the same session does not mean that the platform has stored the messages from the previous turn for the application. Whether history and business state are stored and can be restored depends on the application or managed Harness implementation:

• Declaring a protocol in the AgentCore console does not implement the interface or store history automatically.

• Using only AgentCoreServer does not automatically provide complete history persistence.

• A session ID sent by the debugging panel does not prove that the server has stored or restored the history.

• Using the same session ID in requests for two protocols does not mean that the application automatically converts or shares history across protocols. To continue a conversation across protocols, the application must manage history and state consistently.

Session isolation boundaries

Session isolation means that different sessions do not share history or state that should remain separate. This includes separate conversations of the same end user and conversations of different end users. The platform and caller jointly determine the isolation result, with different responsibilities on each side.

The platform provides session identification and scheduling boundaries. The session ID determines the session to which a request belongs. Routing association for the same session maintains execution continuity, but it does not guarantee permanent binding to the same process. An instance hosts multiple sessions according to Maximum Sessions per instance, and idle sessions are reclaimed based on Session TTL. For details, see Sessions and instance capacity.

The caller determines the actual isolation result. The business generates session IDs, reuses an ID for the same conversation, assigns a new ID to a new conversation, and does not share an ID across separate conversations. The application or framework implements storage and restoration of history and business state. After an instance restart, update, or session reclamation, the application must be able to restore state from persisted data.

For the division of responsibilities for history and state, see Ownership of history and state. For validation methods, see Integration validation.

Sessions and instance capacity

An agent can have multiple runtime instances, and an instance can host multiple sessions. A session ID is not an instance ID. Increasing the number of instances does not increase the number of session IDs carried in a request. The Session configuration item in the AgentCore console refers to the same concept as session in this topic. The following example uses fixed instances for a high-code agent:

If both instances are ready and each hosts five sessions, the configured number of session slots is 2 × 5 = 10. This does not guarantee that 10 long-running requests can execute concurrently or that the actual throughput is 10 QPS. Model quotas, tool latency, memory usage, and instance health all affect the available capacity.

If some instances are not ready, the available capacity can be lower than the configured capacity. When the capacity limit is reached, use the actual error and runtime status, including instance readiness and the number of active sessions, to distinguish among session capacity, application concurrency, and downstream throttling. Increasing Session TTL alone cannot resolve all three issues. A longer TTL can cause idle sessions to occupy capacity for a longer period.

For other agent types that support auto scaling, distinguish between the current number of ready instances and the configured scaling limit. The fixed instance count for high-code agents does not apply to all agent types.

Passing a session ID

AgentCore currently identifies sessions by an HTTP header. When you create a high-code agent, you configure the session ID method, which includes the name of the header that carries the session ID. For example, if the application uses X-AgentCore-Session-ID as the session header:

X-AgentCore-Session-ID: demo-session-01

The request contains two different values:

• X-AgentCore-Session-ID is the header name agreed upon by the agent configuration and the caller. After the agent is created, the caller sends requests with this header name. You can replace it with an existing business header. For an example, see Scenario 4 in Call examples.

• demo-session-01 is the session ID. Reuse it for the same conversation and use a new value for a new conversation. It is not an agent name, instance ID, or API key.

  The caller generates the session ID. You can use an unpredictable ID generated by your business. Do not use personal information, such as an end user's mobile number, as the session ID.

Request structure and session fields

An HTTP request
├─ URL: Selects the protocol endpoint for this call
├─ Headers
│  ├─ Authentication header: Proves that the caller can access the endpoint
│  └─ Session header: Identifies the session to which the request belongs
└─ Body: Uses the format of the selected protocol
   ├─ AG-UI: threadId, runId, messages, and other fields
   └─ Chat Completions: model, messages, stream, and other fields

Call examples

POST /ag-ui/agent HTTP/1.1
Host: <agent-endpoint>
Content-Type: application/json
Accept: text/event-stream
X-AgentCore-Session-ID: demo-session-01
<authentication-header-name>: <actual-authentication-value>

{
  "threadId": "demo-session-01",
  "runId": "demo-run-01",
  "messages": [
    {"id": "demo-message-01", "role": "user", "content": "Introduce the topic of this report."}
  ],
  "state": {},
  "tools": [],
  "context": [],
  "forwardedProps": {}
}

POST /ag-ui/agent HTTP/1.1
Host: <agent-endpoint>
Content-Type: application/json
Accept: text/event-stream
X-AgentCore-Session-ID: demo-session-01
<authentication-header-name>: <actual-authentication-value>

{
  "threadId": "demo-session-01",
  "runId": "demo-run-02",
  "messages": [
    {"id": "demo-message-01", "role": "user", "content": "Introduce the topic of this report."},
    {"id": "demo-message-02", "role": "assistant", "content": "Replace this text with the actual result from the previous turn."},
    {"id": "demo-message-03", "role": "user", "content": "Summarize the conclusions in three points."}
  ],
  "state": {},
  "tools": [],
  "context": [],
  "forwardedProps": {}
}

POST /openai/v1/chat/completions?sessionId=demo-session-02 HTTP/1.1
Host: <agent-endpoint>
Content-Type: application/json
X-AgentCore-Session-ID: demo-session-02
<authentication-header-name>: <actual-authentication-value>

{
  "model": "agentcore",
  "messages": [
    {"role": "user", "content": "Describe what you can do in one sentence."}
  ],
  "stream": false
}

X-Business-Session: demo-session-01

Differences between high-code agents and managed Harnesses

Both agent types must distinguish between which session a request belongs to and what state the session contains. History behavior is specific to each Harness implementation and is not a general capability of all high-code applications.

Integration validation

When you validate routing and isolation, use the instance and session information together with application logs.

Related documents

• Deploy and use a high-code agent

• Use the AgentCore Python SDK