Python: Clarify service session ID scoping

[eavanvalkenburg]

Motivation & Context

Clarifies user-facing guidance around AgentSession.service_session_id when service-managed history is used. The current docs describe it as a lightweight state field, but do not make the OpenAI API key/project scoping behavior or hosted multi-user responsibility explicit.

This helps library users understand that OpenAI resp_* response IDs and conv_* conversation IDs are scoped to the backing API key/project by default, and that hosted agents using one backing key/project for multiple users should bind stored service-side IDs to authenticated users or tenants before resuming.

Description & Review Guide

• What are the major changes?
  • Expanded AgentSession and SessionContext docstrings to describe service_session_id as a service-managed session identifier.
  • Added OpenAI session sample guidance to avoid echoing raw service session IDs to clients and accepting them back unscoped in hosted multi-user apps.
• What is the impact of these changes?
  • Documentation-only clarification; no runtime behavior, API surface, tests, or serialization changes.
• What do you want reviewers to focus on?
  • Whether the terminology avoids confusing service_session_id with background response continuation tokens.
  • Whether the hosted multi-user OpenAI scoping guidance is accurate and appropriately placed in user-facing docs/sample guidance.

Related Issue

N/A — documentation-only clarification; no linked issue.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 95% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Failure Modes, Design Approach

---

Automated review by eavanvalkenburg's agents

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_sessions.py	396	33	91%	112–114, 116–117, 134–135, 137–139, 217–218, 308, 569–573, 622, 628, 662, 733, 737, 747, 887, 903, 1036, 1050–1051, 1074, 1096, 1106, 1148
TOTAL	44490	5346	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
8815	33 💤	0 ❌	0 🔥	2m 11s ⏱️

[Copilot]

Pull request overview

This PR improves user guidance around service_session_id by clarifying that it may represent a provider-issued, service-side continuation handle and by adding multi-user/tenant safety notes to the OpenAI sample.

Changes:

• Add hosted multi-user guidance in the OpenAI session continuation sample to discourage unscoped client round-tripping of service_session_id.
• Refine core session docstrings to better describe what service_session_id represents and how it should be treated.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
python/samples/02-agents/providers/openai/client_with_session.py	Adds cautionary guidance for hosted multi-user apps when persisting/round-tripping service_session_id.
python/packages/core/agent_framework/_sessions.py	Updates SessionContext/AgentSession docstrings to clarify semantics of service_session_id.