Python: [BREAKING] Fix #3613 chat/agent message typing alignment by eavanvalkenburg · Pull Request #3920 · microsoft/agent-framework

eavanvalkenburg · 2026-02-13T12:56:01Z

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

markwallace-microsoft · 2026-02-13T12:58:18Z

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	149	17	88%	85–86, 90–94, 98–102, 265, 293, 460–462
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, 1260, 1262, 1272–1273, 1280, 1282–1283, 1291–1295, 1303–1304, 1306, 1311, 1313
_clients.py	71	3	95%	296, 493, 495
_mcp.py	405	64	84%	98–99, 109–114, 125, 130, 176–177, 187–192, 202–203, 255, 264, 327, 335, 356, 470, 537, 572, 574, 578–579, 581–582, 636, 651, 669, 710, 816, 829–834, 856, 902–903, 909–911, 930, 955–956, 960–964, 981–985, 1129
_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	753	84	88%	165–166, 296, 298, 316–318, 325, 343, 357, 369, 374, 376, 383, 420, 443–445, 494–496, 559, 581, 605–631, 666, 674, 915, 1177, 1234, 1238, 1317–1321, 1339, 1341–1342, 1454, 1458, 1508, 1510, 1526, 1528, 1592, 1619, 1676, 1744, 1922–1923, 1950, 1958, 1971, 1981–1982, 2017, 2073, 2105
_types.py	1027	96	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, 1536, 1538, 1543, 1571, 1619, 1662–1667, 1689, 1694, 1860, 1872, 2115, 2124, 2145, 2240, 2465, 2672, 2742, 2754, 2761, 2772, 2976–2978, 2981–2983, 2987, 2992, 2996, 3108–3110, 3138, 3192, 3196–3198, 3200, 3211–3212, 3215–3219, 3225
observability.py	617	84	86%	336, 338–340, 343–345, 350–351, 357–358, 364–365, 372, 374–376, 379–381, 386–387, 393–394, 400–401, 408, 677, 680, 688–689, 692–695, 697, 700–702, 705–706, 734, 736, 747–749, 751–754, 758, 766, 867, 869, 1018, 1020, 1024–1029, 1031, 1034–1038, 1040, 1152–1153, 1155, 1212–1213, 1348, 1402–1403, 1519–1521, 1580, 1750, 1904, 1906
packages/core/agent_framework/_workflows
_agent.py	346	68	80%	67, 75–81, 117–118, 208, 252, 308, 354–355, 361–362, 368, 370, 375, 435–436, 445, 452, 478, 511–513, 515, 517, 519, 524, 529, 576, 606, 623, 662–665, 671, 677, 681–682, 685–691, 695–696, 702, 763, 770, 776–777, 788, 820, 827, 848, 857, 861, 863–865, 872
_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	20459	3216	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3941	225 💤	0 ❌	0 🔥	1m 9s ⏱️

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,
            ),
        )

python/packages/core/agent_framework/_middleware.py

python/packages/durabletask/agent_framework_durabletask/_shim.py

TaoChenOSU · 2026-02-13T18:45:25Z

python/packages/ag-ui/agent_framework_ag_ui/_client.py

-        from agent_framework._logging import get_logger
-
-        logger = get_logger()
+        logger = logging.getLogger("agent_framework.ag_ui")


Why do we need to create the logger again?

TaoChenOSU · 2026-02-13T18:47:05Z

python/packages/ag-ui/getting_started/client_advanced.py


    stream = client.get_response(
-        "Tell me a short joke",
+        [Message(role="user", text="Tell me a short joke")],


Any reason we remove the support for string? Seems like a very convenient way for people to get started.

Were keeping it at the agent level, but since most people will use that it simplifies and speeds up being able to assume we have messages at the chat client level

python/packages/core/agent_framework/_workflows/_checkpoint_encoding.py

TaoChenOSU · 2026-02-13T18:51:55Z

python/packages/core/agent_framework/_types.py

+AgentRunInputs = str | Content | Message | Sequence[str | Content | Message]
+AgentRunInputsOrNone = AgentRunInputs | None


This really isn't saving much. I wonder if we should just make people do AgentRunInputs | None to make thing more obvious

Co-authored-by: Tao Chen <taochen@microsoft.com>

Copilot AI review requested due to automatic review settings February 13, 2026 12:56

eavanvalkenburg requested a review from a team as a code owner February 13, 2026 12:56

markwallace-microsoft added the python label Feb 13, 2026

github-actions bot changed the title ~~Fix #3613 chat/agent message typing alignment~~ Python: Fix #3613 chat/agent message typing alignment Feb 13, 2026

Copilot started reviewing on behalf of eavanvalkenburg February 13, 2026 12:56 View session

Copilot AI reviewed Feb 13, 2026

View reviewed changes

python/packages/core/agent_framework/_middleware.py Outdated Show resolved Hide resolved

python/packages/durabletask/agent_framework_durabletask/_shim.py Outdated Show resolved Hide resolved

eavanvalkenburg changed the title ~~Python: Fix #3613 chat/agent message typing alignment~~ [BREAKING] Fix #3613 chat/agent message typing alignment Feb 13, 2026

eavanvalkenburg changed the title ~~[BREAKING] Fix #3613 chat/agent message typing alignment~~ Python: [BREAKING] Fix #3613 chat/agent message typing alignment Feb 13, 2026

eavanvalkenburg force-pushed the fix-3613-chatclient-message-types branch from 42aa185 to 8ba0f2f Compare February 13, 2026 14:28

eavanvalkenburg added 6 commits February 13, 2026 16:18

Fix microsoft#3613 message typing across chat and agents

7d92cd3

Address microsoft#3613 review feedback and sample input style

ca642d3

refactor: use shared AgentRunMessages aliases (microsoft#3613)

91a23f5

refactor: rename agent run input aliases for microsoft#3613

9a0e1a0

samples: inline image content in run calls

38c9ccb

core: export AgentRunInputs from package init

838571a

eavanvalkenburg force-pushed the fix-3613-chatclient-message-types branch from 14469dc to 838571a Compare February 13, 2026 15:21

eavanvalkenburg added 2 commits February 13, 2026 16:37

core: use explicit init re-exports without __all__

dc3e037

updated logging and inits

902df61

markwallace-microsoft added the documentation Improvements or additions to documentation label Feb 13, 2026

Fix core mypy export and samples XML note

0bde24c

TaoChenOSU reviewed Feb 13, 2026

View reviewed changes

Update _checkpoint_encoding.py

2f54148

Co-authored-by: Tao Chen <taochen@microsoft.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

Python: [BREAKING] Fix #3613 chat/agent message typing alignment#3920
eavanvalkenburg wants to merge 10 commits intomicrosoft:mainfrom
eavanvalkenburg:fix-3613-chatclient-message-types

eavanvalkenburg commented Feb 13, 2026 •

edited

Loading

Uh oh!

markwallace-microsoft commented Feb 13, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

TaoChenOSU Feb 13, 2026

Uh oh!

TaoChenOSU Feb 13, 2026

Uh oh!

eavanvalkenburg Feb 14, 2026

Uh oh!

Uh oh!

TaoChenOSU Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		AgentRunInputs = str \| Content \| Message \| Sequence[str \| Content \| Message]
		AgentRunInputsOrNone = AgentRunInputs \| None

Conversation

eavanvalkenburg commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

markwallace-microsoft commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python Unit Test Overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

TaoChenOSU Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

TaoChenOSU Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

eavanvalkenburg Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TaoChenOSU Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

eavanvalkenburg commented Feb 13, 2026 •

edited

Loading

markwallace-microsoft commented Feb 13, 2026 •

edited

Loading