Python: [BREAKING] Fix #3613 chat/agent message typing alignment

[eavanvalkenburg]

Summary

• [BREAKING] update chat client get_response contracts to accept only Sequence[Message]
• remove chat-side message normalization and keep message normalization at agent run
• expand agent run inputs to str | Content | Message | Sequence[str | Content | Message] | None
• align dependent implementations (a2a, claude, github_copilot, copilotstudio, durabletask), existing tests, and AG-UI getting-started samples

Closes #3613

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/a2a/agent_framework_a2a
_agent.py	170	9	94%	358, 379, 452–453, 494–495, 524–526
packages/ag-ui/agent_framework_ag_ui
_client.py	147	17	88%	85–86, 90–94, 98–102, 265, 292, 458–460
_message_adapters.py	453	95	79%	90, 100–101, 110–113, 116–120, 122–127, 130, 139–145, 148, 152–154, 163–165, 185, 191–193, 223, 236–237, 247–248, 285, 288, 290, 293, 296, 312, 329, 351, 382, 387, 398–399, 447, 463–464, 530–533, 535, 541, 549–550, 552, 556–559, 572, 661–664, 666, 731, 766–768, 770–773, 776–777, 779, 785, 788, 790, 793, 795, 801–802, 804
packages/anthropic/agent_framework_anthropic
_chat_client.py	364	148	59%	422, 451, 483, 485, 500, 522–525, 534, 536, 573–577, 579, 581–582, 584, 589–590, 592, 625–626, 635, 637–638, 643, 660–661, 705, 728, 737, 739, 743–744, 787–789, 791, 804–805, 812–814, 818–820, 824–827, 838, 840, 862, 872, 894–900, 907–908, 916–917, 925–928, 935–936, 942–943, 949–950, 956, 964–966, 970, 977–978, 984–985, 991–992, 998, 1006–1009, 1016–1017, 1036, 1043–1044, 1063, 1085, 1087, 1096–1097, 1103, 1125–1126, 1132–1133, 1142–1152, 1159–1165, 1172–1178, 1185–1194, 1201–1204
packages/azure-ai-search/agent_framework_azure_ai_search
_context_provider.py	265	131	50%	103–104, 224, 226, 230, 257–258, 260, 269–270, 273–274, 290, 300, 341–342, 355, 363–368, 371–373, 380–382, 387–390, 392–397, 399–405, 409, 413–418, 422, 424, 427–428, 430, 438–440, 443–445, 451, 453–455, 458, 471–472, 474–475, 477, 479–481, 487–488, 490–497, 499–503, 510, 512, 519, 524, 529, 531, 539–540, 542–543, 552, 554, 559, 561, 567–570, 577, 585, 592–594, 596–604, 606, 616–620, 623
packages/azure-ai/agent_framework_azure_ai
_chat_client.py	477	75	84%	387–388, 390, 573, 578–579, 581–582, 585, 588, 590, 595, 856–857, 859, 862, 865, 868–873, 876, 878, 886, 898–900, 904, 907–908, 916–919, 929, 937–940, 942–943, 945–946, 953, 961–962, 970–971, 976–977, 981–988, 993, 996, 1004, 1010, 1018–1020, 1023, 1045–1046, 1179, 1207, 1222, 1338, 1464
_client.py	213	22	89%	372, 374, 423, 452–457, 500, 535, 537, 570, 778, 781, 784–785, 787–790, 837
_project_provider.py	115	4	96%	212, 310, 354, 387
_shared.py	233	17	92%	110, 140, 224, 267, 279–281, 310, 312, 314, 318, 383, 414, 455, 462, 474, 493
packages/azurefunctions/agent_framework_azurefunctions
_app.py	370	69	81%	323–324, 432, 440–441, 461–463, 469–471, 477–479, 512–513, 573–574, 623–624, 629, 711, 714, 723–725, 727–729, 731, 733, 744, 746–749, 751, 753–754, 756, 763–764, 766–767, 769–770, 772, 776, 786–788, 790–791, 793–795, 802, 804–805, 807, 828, 833, 845, 998, 1013–1016, 1041
_entities.py	59	0	100%
_orchestration.py	61	0	100%
packages/copilotstudio/agent_framework_copilotstudio
_agent.py	80	3	96%	170, 178, 295
packages/core/agent_framework
_agents.py	311	39	87%	474, 874, 910, 987–990, 1054–1056, 1170, 1183, 1196, 1202, 1238, 1240, 1249–1254, 1259, 1261, 1267–1268, 1275, 1277–1278, 1286–1287, 1290–1292, 1300–1301, 1303, 1308, 1310
_clients.py	71	3	95%	296, 493, 495
_mcp.py	403	63	84%	96–97, 107–112, 123, 128, 174–175, 185–190, 200–201, 253, 262, 325, 333, 468, 535, 570, 572, 576–577, 579–580, 634, 649, 667, 708, 813, 826–831, 853, 899–900, 906–908, 927, 952–953, 957–961, 978–982, 1126
_middleware.py	328	16	95%	60, 63, 68, 775, 777, 779, 900, 927, 929, 954, 1035, 1039, 1163, 1167, 1228, 1302
_serialization.py	106	5	95%	290, 494, 510, 520, 588
_sessions.py	167	16	90%	67–69, 71–74, 91–92, 94–98, 539, 553
_settings.py	106	11	89%	92, 99, 115, 126, 142–143, 145, 148, 244–245, 250
_telemetry.py	19	1	94%	59
_tools.py	815	113	86%	162–163, 300, 302, 320–322, 329, 347, 361, 368, 375, 391, 393, 400, 437, 462, 466, 483–485, 534–536, 599, 621, 645–671, 706, 717–728, 750–752, 757, 761, 775–777, 816, 885, 895, 905, 961, 992, 1011, 1273, 1330, 1334, 1350, 1421–1425, 1443, 1445–1446, 1558, 1562, 1612, 1614, 1630, 1632, 1696, 1723, 1780, 1848, 2026–2027, 2054, 2062, 2075, 2085–2086, 2121, 2177, 2209
_types.py	1008	92	90%	48, 57–58, 112, 117, 136, 138, 142, 146, 148, 150, 152, 170, 174, 200, 222, 227, 232, 236, 262, 266, 612–613, 984, 1046, 1063, 1081, 1086, 1104, 1114, 1131–1132, 1134, 1152–1153, 1155, 1162–1163, 1165, 1200, 1211–1212, 1214, 1252, 1479, 1531, 1622–1627, 1649, 1654, 1820, 1832, 2075, 2084, 2105, 2200, 2425, 2632, 2702, 2714, 2721, 2732, 2936–2938, 2941–2943, 2947, 2952, 2956, 3068–3070, 3098, 3152, 3156–3158, 3160, 3171–3172, 3175–3179, 3185
observability.py	616	83	86%	335, 337–339, 342–344, 349–350, 356–357, 363–364, 371, 373–375, 378–380, 385–386, 392–393, 399–400, 407, 676, 679, 687–688, 691–694, 696, 699–701, 704–705, 733, 735, 746–748, 750–752, 756, 764, 865, 867, 1016, 1018, 1022–1027, 1029, 1032–1036, 1038, 1150–1151, 1153, 1210–1211, 1346, 1400–1401, 1517–1519, 1578, 1748, 1902, 1904
packages/core/agent_framework/_workflows
_agent.py	346	68	80%	66, 74–80, 116–117, 207, 251, 307, 353–354, 360–361, 367, 369, 374, 434–435, 444, 451, 477, 510–512, 514, 516, 518, 523, 528, 575, 605, 622, 661–664, 670, 676, 680–681, 684–690, 694–695, 701, 762, 769, 775–776, 787, 819, 826, 847, 856, 860, 862–864, 871
_checkpoint_encoding.py	50	2	96%	163–164
_message_utils.py	21	5	76%	21, 27, 35, 37, 41
packages/core/agent_framework/azure
_assistants_client.py	40	0	100%
_chat_client.py	78	4	94%	302, 304, 317–318
_responses_client.py	50	6	88%	187, 219, 285–288
packages/core/agent_framework/openai
_assistant_provider.py	108	9	91%	171, 296, 362, 477–482
_assistants_client.py	273	34	87%	407, 409, 411, 414, 418–419, 422, 425, 430–431, 433, 436–438, 443, 454, 479, 481, 483, 485, 487, 492, 495, 498, 502, 513, 598, 683, 712, 749–752, 822
_chat_client.py	268	23	91%	200, 230–231, 235, 349, 356, 437–444, 446–449, 459, 544, 579, 595, 635
_exceptions.py	33	0	100%
_responses_client.py	612	79	87%	291–294, 298–299, 302–303, 309–310, 315, 328–334, 355, 363, 386, 549, 552, 607, 611, 613, 615, 617, 693, 703, 708, 751, 828, 845, 858, 914, 1007, 1012, 1016–1018, 1022–1023, 1046, 1115, 1137–1138, 1153–1154, 1172–1173, 1304–1305, 1321, 1323, 1402–1410, 1505, 1560, 1575, 1611–1612, 1614–1616, 1630–1632, 1642–1643, 1649, 1664
_shared.py	127	16	87%	66, 72–75, 150, 152, 154, 161, 163, 176, 251, 275, 334–335, 337
packages/declarative/agent_framework_declarative
_models.py	467	36	92%	16, 19, 51, 56, 225–232, 487, 528–531, 555, 563, 571, 579, 602, 628, 652, 680, 790, 852, 964, 1090, 1092, 1094, 1096, 1098, 1100, 1104, 1106
packages/declarative/agent_framework_declarative/_workflows
_actions_agents.py	317	229	27%	57, 59–60, 62, 64–65, 68–71, 75, 79–81, 83–87, 91, 93–94, 96–106, 108–109, 112–117, 119–120, 122–124, 126–128, 130–132, 134–135, 137–141, 143–151, 153, 155, 158–159, 162, 184, 218, 220–222, 227–228, 242–243, 245, 271–272, 276–277, 287–306, 311, 316–319, 351, 354–355, 361–362, 365–367, 370, 377–378, 381–383, 385–386, 388–390, 395–397, 401, 404–405, 407, 435–436, 439–442, 447–449, 453, 457, 466–467, 469–471, 476–477, 479, 484, 486–487, 500, 506, 509–512, 527, 529–530, 532, 534, 550–557, 560–563, 566, 569, 572, 575–579, 581, 584–586, 588–589, 591, 594–595, 597–598, 600–601, 603–604, 610–612, 614, 616–617, 619–620, 622, 628, 630–632, 634, 636–637, 639–640, 642, 648, 650–652
_actions_basic.py	241	98	59%	53–54, 77–78, 80–82, 85, 88, 90–91, 93, 109, 111, 113, 129–130, 162–164, 167–168, 183–184, 186–189, 207–208, 227–239, 241–242, 244–245, 266–267, 273, 303–304, 327–328, 417–418, 434, 464–466, 468–470, 473–474, 477, 479–480, 483–484, 487–488, 491–496, 498, 505, 520–522, 524–526, 529, 532–534, 537–538, 541–545, 547
_actions_control_flow.py	168	52	69%	45–46, 52–53, 56–57, 72–78, 80–81, 83, 103–104, 122, 147–148, 171, 190–191, 203–210, 212, 215, 220–221, 234–235, 245–246, 277–278, 294, 302, 317, 319–321, 323, 326, 337, 392
_actions_error.py	52	7	86%	98, 107–109, 114, 123, 131
_factory.py	137	60	56%	180, 257–258, 322–324, 332, 334, 337–343, 372, 383–384, 393, 428, 441, 466–469, 488–492, 495–496, 499, 502, 507, 616–617, 619–620, 622–624, 627, 641, 644–649, 652–653, 655, 658, 668–669, 671, 675–676, 678
_handlers.py	83	0	100%
_human_input.py	124	12	90%	108–109, 117, 169–170, 175–176, 196–197, 218–219, 289
_state.py	309	164	46%	22, 25, 141, 165, 179, 201–202, 204, 220, 228, 236, 242, 244, 254, 362, 375–376, 380, 398, 400, 403–406, 409–412, 415–417, 419–425, 428–432, 435–439, 442–458, 461–464, 466–469, 471–474, 476–479, 481–488, 491–494, 496–503, 506–509, 511–517, 519–523, 526–527, 530–535, 538–541, 544, 547–552, 555, 566–570, 572–589, 591, 593–594, 596
packages/purview/agent_framework_purview
_client.py	120	0	100%
_middleware.py	112	0	100%
_models.py	457	96	78%	222–226, 308, 310, 332, 334, 338, 365, 369, 416–421, 424–431, 442–445, 456–459, 489–490, 493, 495, 497–499, 533, 535, 537, 539, 541, 543, 545, 550–552, 554, 557, 563, 566, 605, 607, 609, 611, 613, 621, 623, 625, 627, 661, 665, 700, 702, 704, 708, 714, 716, 738–739, 764, 766, 768, 772, 791–793, 798–799, 832, 834, 846, 909, 912–916, 918, 946, 977, 979
_processor.py	171	10	94%	177, 257–260, 265, 293, 295, 301, 303
TOTAL	20495	3239	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3946	225 💤	0 ❌	0 🔥	1m 8s ⏱️

[Copilot]

Pull request overview

This PR aligns Python chat-client and agent message-input typing to resolve #3613: chat clients now accept Sequence[Message] only (removing chat-side normalization), while agents accept broader “run inputs” including Content (and nullable variants), with downstream implementations, tests, and samples updated accordingly.

Changes:

• Updated chat client contracts and middleware layers to take messages: Sequence[Message] and removed implicit normalization.
• Updated agent run() contracts to accept str | Content | Message | Sequence[str | Content | Message] | None.
• Updated downstream agent packages plus tests/samples to match the new typing.

Reviewed changes

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

Show a summary per file

File	Description
python/packages/orchestrations/tests/test_magentic.py	Updates agent run() typing in orchestrations tests to include Content.
python/packages/orchestrations/tests/test_group_chat.py	Updates agent run() typing in group chat tests to include Content.
python/packages/github_copilot/agent_framework_github_copilot/_agent.py	Aligns GitHub Copilot agent run() overloads/impl typing with new agent message union.
python/packages/durabletask/agent_framework_durabletask/_shim.py	Updates DurableTask shim run() typing and switches to normalize_messages() for string conversion.
python/packages/core/tests/workflow/test_workflow_kwargs.py	Updates workflow test agents’ run() message typing to include Content.
python/packages/core/tests/workflow/test_workflow.py	Updates workflow test agent run() message typing to include Content.
python/packages/core/tests/workflow/test_full_conversation.py	Updates workflow test agent run() message typing to include Content.
python/packages/core/tests/workflow/test_agent_executor_tool_calls.py	Updates executor test agent run() message typing to include Content.
python/packages/core/tests/core/test_function_invocation_logic.py	Updates chat client calls to pass Sequence[Message] instead of str.
python/packages/core/tests/core/test_clients.py	Updates core client tests to pass Sequence[Message] consistently (streaming and non-streaming).
python/packages/core/tests/core/test_agents.py	Adds coverage for agent.run(Content.from_text(...)).
python/packages/core/agent_framework/observability.py	Aligns telemetry-layer chat contract to Sequence[Message] and agent contract to new union.
python/packages/core/agent_framework/_workflows/_message_utils.py	Extends workflow normalization helper to support Content inputs.
python/packages/core/agent_framework/_workflows/_agent.py	Updates workflow agent run() typing to support Content and mixed input sequences.
python/packages/core/agent_framework/_tools.py	Updates function-invocation layer to accept Sequence[Message] and removes message prepping.
python/packages/core/agent_framework/_middleware.py	Updates middleware-layer chat contract to Sequence[Message] and adjusts context creation.
python/packages/core/agent_framework/_clients.py	Updates core chat client protocol/base signatures and examples to require Sequence[Message].
python/packages/core/agent_framework/_agents.py	Updates agent contracts to accept Content and mixed sequences for run().
python/packages/copilotstudio/agent_framework_copilotstudio/_agent.py	Aligns Copilot Studio agent run() typing with new agent message union.
python/packages/claude/agent_framework_claude/_agent.py	Aligns Claude agent run() typing with new agent message union.
python/packages/ag-ui/tests/ag_ui/conftest.py	Updates AG-UI test stubs’ typing to include Content.
python/packages/ag-ui/getting_started/client_advanced.py	Updates sample usage to pass Sequence[Message] into get_response().
python/packages/ag-ui/getting_started/client.py	Updates sample usage to pass Sequence[Message] into get_response().
python/packages/a2a/agent_framework_a2a/_agent.py	Aligns A2A agent run() typing with new agent message union.

Comments suppressed due to low confidence (1)

python/packages/ag-ui/tests/ag_ui/conftest.py:103

• StreamingChatClientStub.get_response is typed to accept str | Content | Message | Sequence[str | Content | Message], but it forwards messages directly to BaseChatClient.get_response, which now requires Sequence[Message] and no longer normalizes inputs. This makes the stub’s signature misleading and will raise at runtime if tests (or future callers) pass a str/Content/Message or Sequence[str|Content]. Either narrow the stub’s messages parameter to Sequence[Message] (matching the new contract) or normalize to Sequence[Message] before calling super().get_response.

    def get_response(
        self,
        messages: str | Content | Message | Sequence[str | Content | Message],
        *,
        stream: bool = False,
        options: OptionsCoT | ChatOptions[Any] | None = None,
        **kwargs: Any,
    ) -> Awaitable[ChatResponse[Any]] | ResponseStream[ChatResponseUpdate, ChatResponse[Any]]:
        self.last_session = kwargs.get("session")
        self.last_service_session_id = self.last_session.service_session_id if self.last_session else None
        return cast(
            Awaitable[ChatResponse[Any]] | ResponseStream[ChatResponseUpdate, ChatResponse[Any]],
            super().get_response(
                messages=messages,
                stream=cast(Literal[True, False], stream),
                options=options,
                **kwargs,
            ),
        )