Skip to content

Python: Clarify service session ID scoping #6993

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
giles17 merged 1 commit into from
Jul 8, 2026
+15 −4
Merged

Python: Clarify service session ID scoping #6993

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions python/packages/core/agent_framework/_sessions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Comment thread
eavanvalkenburg marked this conversation as resolved.
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).
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Comment thread
eavanvalkenburg marked this conversation as resolved.

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).
Comment thread
eavanvalkenburg marked this conversation as resolved.
state: Mutable state dict shared with all providers.
"""

Expand All @@ -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
Expand Down
3 changes: 3 additions & 0 deletions python/samples/02-agents/providers/openai/client_with_session.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
Expand Down
Loading