Align Foundry sessions with Responses continuity

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3e5c81ad-75e8-4e92-a883-8bbd676c6c8c
Eduard van Valkenburg (eavanvalkenburg) · Jul 30, 2026 · Jul 24, 2026 · Jul 27, 2026 · Jul 27, 2026 · Jul 27, 2026
commit 934a03efb7c52887888c3b6384cae196e41a92ce
diff --git a/docs/decisions/0033-python-session-store-serialization.md b/docs/decisions/0033-python-session-store-serialization.md
@@ -210,17 +210,27 @@ Foundry Hosting exposes an experimental `FoundrySessionStore`, which is the
 default `ResponsesHostServer` store when hosted; local hosting defaults to the
 in-memory `SessionStore`. `FoundrySessionStore` currently subclasses
 `FileSessionStore`, stores snapshots under
-`/.sessions/<user-id>/<session-id>.json`, and derives the validated platform
-IDs from `azure.ai.agentserver.core.get_request_context()`. A Foundry session
-controls hosted compute and filesystem lifetime, while a MAF `AgentSession`
-contains framework context state; using the same identifier correlates them but
-does not make their semantics equivalent. Callers can override the default
-through `session_store=` when snapshots must be stored outside Foundry, such as
-in a database or blob store. The Foundry-specific type is the host configuration
-seam; its implementation may later move from files to a Foundry storage API
-without changing the generic core store contract. The session file API maps `/`
-to the hosted `$HOME` directory, so this API path is persisted on disk under
-`$HOME/.sessions`.
+`/.sessions/<user-id>/<conversation-id-or-response-id>.json`, and derives the
+validated user partition from
+`azure.ai.agentserver.core.get_request_context()`. A Foundry session controls
+hosted compute and filesystem lifetime and may host multiple users and
+Responses conversations, so its ID is not used as the MAF session identifier.
+Stored-conversation requests read and write one snapshot under
+`conversation_id`. Response-chain requests read under `previous_response_id`
+and write the updated, loaded MAF session under the current `response_id`, which
+allows branching without overwriting the parent snapshot. Because Foundry does
+not infer `agent_session_id` from `previous_response_id`, response-chain callers
+must also reuse the prior response's hosted session ID so the request reaches
+the same persistent `$HOME`; conversation objects bind a stable hosted session
+automatically. Callers can override the default through `session_store=` when
+snapshots must be stored outside Foundry, such as in a database or blob store.
+The host passes the same raw Responses IDs to every store implementation;
+custom stores are responsible for any backend-specific user, tenant, or agent
+partitioning.
+The Foundry-specific type is the host configuration seam; its implementation
+may later move from files to a Foundry storage API without changing the generic
+core store contract. The session file API maps `/` to the hosted `$HOME`
+directory, so this API path is persisted on disk under `$HOME/.sessions`.
 
 ### Decision 2: Use msgspec codecs plus an explicit dynamic registry
 

@@ -6,10 +6,13 @@ This package provides the integration of Agent Framework agents and workflows wi
 agents in addition to the Responses provider's message history. By default it
 uses the experimental `FoundrySessionStore` under `/.sessions` when hosted and
 an in-memory `SessionStore` locally. Hosted snapshots are partitioned by the
-Agent Server request context's platform user ID, and their filenames come from
-its platform session ID. Pass `session_store=` to explicitly override either
+Agent Server request context's platform user ID. Snapshot filenames use the
+Responses `conversation_id` or `response_id`, depending on the continuation
+mode. Pass `session_store=` to explicitly override either
 default when MAF session snapshots must be stored outside Foundry, such as in a
-database or blob store.
+database or blob store. Every store receives the same raw Responses
+`conversation_id`, `previous_response_id`, and `response_id` key semantics.
+Custom stores own any backend-specific user, tenant, or agent isolation.
 
 Foundry's session file API exposes the hosted `$HOME` directory as `/`, so the
 API path `/.sessions` is stored on disk at `$HOME/.sessions`.
@@ -24,16 +27,27 @@ validates the platform `user_id` (the same `x-agent-user-id` value exposed as
 `ResponseContext.platform_context.user_id_key`) before selecting its on-disk
 directory.
 
-Regular-agent session snapshots use the platform user and session IDs:
+Regular-agent session snapshots use the platform user ID and a Responses key:
 
 ```text
-/.sessions/<user-id>/<session-id>.json
+/.sessions/<user-id>/<conversation-id-or-response-id>.json
 ```
 
-A Foundry session controls hosted compute and filesystem lifetime. A MAF
-`AgentSession` contains framework context state. Responses hosting uses the same
-identifier to correlate and locate the snapshot, but the two session concepts
-do not otherwise share lifecycle semantics.
+A Foundry session controls hosted compute and filesystem lifetime and may host
+multiple users and Responses conversations. The Foundry session ID is not used
+as the MAF session identifier.
+
+When `conversation_id` is used, the host reads and writes the same snapshot
+under that ID. When `previous_response_id` is used, the host reads that response
+snapshot, runs the loaded MAF session, and writes the updated snapshot under the
+current response's `response_id`. Multiple responses can therefore branch from
+one prior response without overwriting its snapshot.
+
+Foundry does not infer the hosted `agent_session_id` from
+`previous_response_id`. Callers using response chains must also reuse the
+`agent_session_id` returned by the previous response so the request reaches the
+same sandbox and `$HOME/.sessions` filesystem. Conversation objects bind to a
+stable hosted session automatically.
 
 Workflow checkpoints and function approvals preserve the existing Foundry
 Hosting layout. Hosted paths insert the validated raw platform user ID:
@@ -49,7 +63,7 @@ function approvals remain in memory.
 Hosted requests require container protocol `2.0.0`. The v2-only request
 `call_id` is checked before session, checkpoint, or approval storage is used,
 and a missing platform user ID fails closed. Regular agents also require the
-platform session ID used for their snapshot filename. Local requests may remain
+normal Responses continuation ID for restoration. Local requests may remain
 unscoped.
 
 The Foundry-specific store type intentionally hides the current filesystem