From 3c7cc8dabe62881d589deedda4b441abb55315e6 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 8 Jul 2026 13:32:41 +0200 Subject: [PATCH] Clarify service session ID scoping Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../packages/core/agent_framework/_sessions.py | 16 ++++++++++++---- .../providers/openai/client_with_session.py | 3 +++ 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/python/packages/core/agent_framework/_sessions.py b/python/packages/core/agent_framework/_sessions.py index b896cafccb..8c1624525b 100644 --- a/python/packages/core/agent_framework/_sessions.py +++ b/python/packages/core/agent_framework/_sessions.py @@ -166,7 +166,8 @@ class SessionContext: Attributes: session_id: The ID of the current session. - service_session_id: Service-managed session ID (if present, service handles storage). + service_session_id: Service-managed session identifier + (if present, the service stores history). input_messages: The new messages being sent to the agent (set by caller). context_messages: Dict mapping source_id -> messages added by that provider. Maintains insertion order (provider execution order). @@ -196,7 +197,7 @@ def __init__( Args: session_id: The ID of the current session. - service_session_id: Service-managed session ID. + service_session_id: Service-managed session identifier. input_messages: The new messages being sent to the agent. context_messages: Pre-populated context messages by source. instructions: Pre-populated instructions. @@ -756,9 +757,16 @@ class AgentSession: Lightweight state container. Provider instances are owned by the agent, not the session. The session only holds session IDs and a mutable state dict. + ``service_session_id`` can contain a provider-issued service session + identifier, such as a service conversation ID or response ID. Treat this + value as trusted application state: it is scoped by the backing API key, + service account, or project, but it is not an end-user authorization + boundary by itself. + Attributes: session_id: Unique identifier for this session. - service_session_id: Service-managed session ID (if using service-side storage). + service_session_id: Service-managed session identifier + (if using service-side storage). state: Mutable state dict shared with all providers. """ @@ -772,7 +780,7 @@ def __init__( Args: session_id: Optional session ID (generated if not provided). - service_session_id: Optional service-managed session ID. + service_session_id: Optional service-managed session identifier. """ self._session_id = session_id or str(uuid.uuid4()) self.service_session_id = service_session_id diff --git a/python/samples/02-agents/providers/openai/client_with_session.py b/python/samples/02-agents/providers/openai/client_with_session.py index f9e398ca99..3d0eed4d0b 100644 --- a/python/samples/02-agents/providers/openai/client_with_session.py +++ b/python/samples/02-agents/providers/openai/client_with_session.py @@ -123,6 +123,9 @@ async def example_with_existing_session_id() -> None: if existing_session_id: print("\n--- Continuing with the same session ID in a new agent instance ---") + # In a hosted multi-user app, do not echo this service session ID to clients + # and accept it back unscoped. OpenAI scopes it to the API key/project, so + # store it server-side and verify it belongs to the authenticated user or tenant. agent = Agent( client=OpenAIChatClient(), instructions="You are a helpful weather agent.",