feat(a2a): add A2AAgentSession with reference_task_ids and input-required support

[giles17]

Summary

Introduces A2AAgentSession — a typed session class that tracks A2A conversation state (context_id, task_id, task_state) — and uses it to implement two features:

1. Reference task IDs (Python: [A2A] Link follow-up messages to the existing task via reference_task_ids #5938): Follow-up messages link to previous tasks via reference_task_ids for task refinement
2. Input-required support (Python: [A2A] First-class support for input-required user input #5937): When the remote agent needs user input, the framework:
   • Sets task_id (not reference_task_ids) on the next outgoing message to continue the same task
   • Gates status content to only surface INPUT_REQUIRED and terminal states (matches .NET GetUserInputRequests pattern)
   • Marks updates with additional_properties["input_required"] = True for caller distinction

Changes

A2AAgentSession (new class)

• Subclasses AgentSession with typed context_id, task_id, task_state properties
• Tracks state from all stream payload types (task, status_update, artifact_update, message)
• Validates context_id consistency across responses
• Exported from agent_framework.a2a (lazy-loaded)

_prepare_message_for_a2a

• Accepts session parameter, reads A2A state internally
• Branches on task_state: INPUT_REQUIRED → task_id, else → reference_task_ids

_updates_from_task_update_event

• Gates TaskStatusUpdateEvent content: only emits parts for INPUT_REQUIRED and terminal states
• Intermediate status text (WORKING, SUBMITTED) is not surfaced to callers
• Sets input_required: True in additional_properties when state is INPUT_REQUIRED

Stream handler (_map_a2a_stream)

• Tracks context_id from message payloads
• Treats INPUT_REQUIRED as immediate-yield (not accumulated) in non-streaming mode
• Persists session state on last_task_id or last_context_id

.NET Parity

Mirrors the behavior of A2AAgent.cs:

• CreateA2AMessage (lines 362-382): INPUT_REQUIRED → task_id, else → reference_task_ids
• GetUserInputRequests extension: content only for INPUT_REQUIRED state
• UpdateSession (lines 323-342): context_id validation, task_id/state tracking

Testing

• 139 tests passing (includes new tests for content gating, input_required flag, reference_task_ids, session state tracking)
• Pyright clean

Closes

• Python: [A2A] Link follow-up messages to the existing task via reference_task_ids #5938
• Python: [A2A] First-class support for input-required user input #5937

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/a2a/agent_framework_a2a
_agent.py	367	22	94%	254, 262, 453, 458, 460, 515–516, 546–547, 551, 693, 709, 721, 748, 769, 816, 832, 842, 853, 860–861, 912
TOTAL	35379	4108	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
7036	30 💤	0 ❌	0 🔥	1m 50s ⏱️

[Copilot]

Pull request overview

Adds A2A task-refinement linking in the Python A2A agent by persisting the most recently observed task_id and attaching it to subsequent outbound messages via reference_task_ids, enabling remote agents to correlate follow-up turns to the prior task per the A2A “life of a task” refinement flow.

Changes:

• Persist the last seen A2A task_id onto session.state["a2a_task_id"] while mapping A2A stream payloads (task, status_update, artifact_update, message).
• When sending a new message with an existing session task id, append it to the outbound A2AMessage.reference_task_ids.
• Add a focused test suite covering first-turn behavior, follow-ups, and task_id tracking across payload types.

Reviewed changes

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

File	Description
python/packages/a2a/agent_framework_a2a/_agent.py	Tracks the last observed task id from incoming A2A stream items and includes it as reference_task_ids on follow-up outbound messages.
python/packages/a2a/tests/test_a2a_agent.py	Adds tests validating reference_task_ids behavior and task id persistence across different response payload types and session/no-session flows.

[giles17]

Automated Code Review

Reviewers: 4 | Confidence: 84% | Result: All clear

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

---

Automated review by giles17's agents