Python: implement ADR-0029 service_session_id lifecycle mapping

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

This implements the accepted ADR-0029 decision for Python session identity lifecycles, where durable provider continuation state lives in AgentSession.service_session_id and can be structured when needed (A2A immediate case).

It addresses the current mismatch between lifecycle intent and implementation by separating:

• durable future-call continuation state,
• per-run/request identity forwarding,
• telemetry conversation id extraction.

This work follows the design direction that originated in #4893 and was finalized in ADR-0029.

Description & Review Guide

• What are the major changes?

• Extend core session typing so service_session_id supports str | ServiceSessionId | None.

• Add agent-owned conversation-id extraction hooks in core:

  • _get_chat_conversation_id(...) for generic provider forwarding (string-only; early error on incompatible structured values)
  • _get_otel_conversation_id(...) for telemetry mapping.

• Update AgentTelemetryLayer to use the agent extraction hook instead of directly reading session.service_session_id.

• Introduce A2AServiceSessionId and migrate A2A durable state (context_id, task_id, task_state) to structured service_session_id.

• Keep A2AAgentSession as compatibility shim and emit a deprecation warning.

• Update lazy exports/stubs and core/a2a tests accordingly.

• What is the impact of these changes?

• Aligns Python behavior with ADR-0029 lifecycle rules.

• Enables structured durable continuation state for A2A without overloading generic chat forwarding.

• Improves failure mode for incompatible sessions by raising early in generic chat paths.

• Preserves backward compatibility for existing serialized string sessions and existing A2A usage (with deprecation guidance).

• What do you want reviewers to focus on?

• Correctness of lifecycle boundaries between session continuation, request forwarding, and telemetry.

• A2A mapping semantics for context_id / task_id / task_state and compatibility behavior.

• Whether early error behavior in generic chat paths is appropriately scoped and actionable.

Related Issue

Fixes #4673
Related to #4893

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]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/a2a/agent_framework_a2a
_a2a_executor.py	93	0	100%
_agent.py	401	25	93%	157–158, 172–173, 311, 546, 551, 553, 607–608, 638–639, 643, 794, 810, 822, 844, 865, 904, 920, 930, 941, 948–949, 1000
packages/claude/agent_framework_claude
_agent.py	319	28	91%	407–408, 412, 424, 432–434, 436–437, 467–469, 488, 492, 494, 498, 507, 553, 556, 596, 601–602, 676, 763, 789–792
packages/copilotstudio/agent_framework_copilotstudio
_agent.py	94	4	95%	174, 182, 252, 284
packages/core/agent_framework
_agents.py	431	50	88%	64, 516, 528, 583, 1083, 1128, 1201–1205, 1304, 1332, 1369, 1391, 1411–1412, 1417, 1506, 1534, 1547, 1598, 1600, 1609–1614, 1619, 1621, 1627–1628, 1635, 1637–1638, 1646–1647, 1650–1652, 1662–1667, 1671, 1676, 1678
_sessions.py	396	33	91%	106–108, 110–111, 128–129, 131–133, 210–211, 301, 562–566, 615, 621, 655, 726, 730, 740, 873, 889, 1022, 1036–1037, 1060, 1082, 1092, 1134
observability.py	1011	87	91%	408, 410–411, 414, 417, 420–421, 426–427, 433–434, 440–441, 448, 450–452, 455–457, 462–463, 469–470, 476–477, 484, 661–662, 861, 865–867, 869, 873–874, 878, 916, 918, 929–931, 933–935, 939, 947, 1071–1072, 1307, 1582–1583, 1694, 1841, 1880–1881, 2063, 2346–2349, 2355, 2381–2382, 2410–2421, 2540, 2543, 2555, 2572, 2576–2577, 2580, 2586, 2695, 2912, 2914
packages/durabletask/agent_framework_durabletask
_models.py	161	11	93%	41, 44, 63, 66, 71, 76, 93, 155, 195–196, 320
_shim.py	45	4	91%	48, 122, 143, 165
packages/github_copilot/agent_framework_github_copilot
_agent.py	375	17	95%	55–56, 104, 113–115, 119, 522, 537–538, 846–847, 886, 889, 1012, 1035, 1076
packages/purview/agent_framework_purview
_middleware.py	121	0	100%
TOTAL	43303	5152	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
8543	37 💤	0 ❌	0 🔥	2m 17s ⏱️

[github-actions]

Automated Code Review

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

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

---

Automated review by eavanvalkenburg's agents

[Copilot]

Pull request overview

Implements ADR-0029’s Python session identity lifecycle mapping by allowing AgentSession.service_session_id to carry either a simple string (generic provider continuation) or a structured mapping (durable provider continuation state), while separating chat forwarding vs. telemetry conversation-id extraction. Updates A2A to persist context_id/task_id/task_state in a structured service_session_id, and keeps A2AAgentSession as a deprecated compatibility wrapper.

Changes:

• Extend core session typing to support service_session_id: str | ServiceSessionId | None and introduce agent-owned hooks for extracting (a) provider chat conversation id and (b) OTel conversation id.
• Update telemetry to use the agent hook for gen_ai.conversation.id instead of directly reading session.service_session_id.
• Add A2AServiceSessionId and migrate A2A durable continuation state into structured service_session_id, plus update exports/docs/tests and add a deprecation warning for A2AAgentSession.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/_sessions.py	Adds ServiceSessionId alias and broadens service_session_id typing for SessionContext/AgentSession.
python/packages/core/agent_framework/_agents.py	Introduces _get_chat_conversation_id and _get_otel_conversation_id; routes chat continuation and per-service-call history logic through the chat-extraction hook.
python/packages/core/agent_framework/observability.py	Uses agent-provided OTel conversation-id extraction hook when available (fallback to string service_session_id).
python/packages/core/agent_framework/init.py	Re-exports ServiceSessionId from the top-level package.
python/packages/core/agent_framework/a2a/init.py	Adds lazy export for A2AServiceSessionId.
python/packages/core/agent_framework/a2a/init.pyi	Updates stub exports to include A2AServiceSessionId.
python/packages/core/AGENTS.md	Documents ServiceSessionId and its role in AgentSession.service_session_id.
python/packages/a2a/agent_framework_a2a/_agent.py	Defines A2AServiceSessionId, persists A2A durable continuation state into structured service_session_id, and adds A2AAgentSession deprecation warning + compatibility syncing.
python/packages/a2a/agent_framework_a2a/init.py	Exports A2AServiceSessionId from the A2A package.
python/packages/a2a/AGENTS.md	Documents new A2A structured session-id shape and deprecation guidance for A2AAgentSession.
python/packages/a2a/tests/test_a2a_agent.py	Updates/extends tests for structured service_session_id persistence, OTel mapping, and deprecation warning behavior.
python/packages/core/tests/core/test_sessions.py	Adds coverage for structured service_session_id acceptance and serialization round-trip.
python/packages/core/tests/core/test_agents.py	Adds tests for structured get_session input and early rejection of structured ids in generic chat agent runs.
python/packages/core/tests/core/test_harness_agent.py	Updates harness test agent get_session typing to accept structured service_session_id.
python/packages/core/tests/core/test_harness_background_agents.py	Updates background agent test get_session typing to accept structured service_session_id.
python/packages/core/tests/workflow/test_workflow_agent.py	Updates workflow test scaffolding get_session typing to accept structured service_session_id.
python/packages/core/tests/workflow/test_full_conversation.py	Updates test private attribute typing to allow structured service_session_id.
python/packages/core/tests/workflow/test_agent_utils.py	Updates test agent protocol typing/imports for structured service_session_id.