Python: [BREAKING] Renamed AgentProtocol to SupportsAgentRun

[dmytrostruk]

Motivation and Context

Resolves: #3616

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/ag-ui/agent_framework_ag_ui
_agent.py	36	1	97%	62
_endpoint.py	46	1	97%	92
_run.py	481	121	74%	155–162, 305, 324–325, 340–341, 356, 384–386, 411, 414–417, 419–420, 423–429, 432–434, 437, 453–455, 462, 468–470, 474, 479–481, 483–484, 500–504, 515, 528, 530–531, 547, 568–569, 626–628, 640–642, 840, 851–852, 859, 877–879, 913–915, 932, 938, 946, 948, 984–990, 993–996, 998–1007, 1010, 1018–1021, 1028, 1031–1032, 1037, 1043–1045, 1049, 1054–1057, 1071–1073
packages/ag-ui/agent_framework_ag_ui/_orchestration
_tooling.py	57	0	100%
packages/azurefunctions/agent_framework_azurefunctions
_app.py	368	85	76%	202–203, 208–209, 320–321, 429, 437–438, 458–460, 466–468, 474–476, 509–510, 570–571, 620–621, 626, 708, 711, 720–722, 724–726, 728, 730, 741, 743–746, 748, 750–751, 753, 760–761, 763–764, 766–767, 769, 773, 783–785, 787–788, 790–792, 799, 801–802, 804, 825, 830, 842, 917, 927, 934–936, 981, 995, 1006–1008, 1010–1013, 1038, 1045, 1047, 1050
_entities.py	57	5	91%	81, 110–112, 114
packages/core/agent_framework
_agents.py	320	35	89%	473, 885, 921, 1020–1022, 1135, 1176, 1178, 1187–1192, 1198, 1200, 1210–1211, 1218, 1220–1221, 1229–1233, 1241–1242, 1244, 1249, 1251, 1285, 1325, 1345
_middleware.py	329	16	95%	80, 83, 88, 797, 799, 801, 922, 949, 951, 976, 1057, 1061, 1185, 1189, 1250, 1324
observability.py	607	84	86%	334, 336–338, 341–343, 348–349, 355–356, 362–363, 370, 372–374, 377–379, 384–385, 391–392, 398–399, 406, 662, 665, 673–674, 677–680, 682, 685–687, 690–691, 719, 721, 732–734, 736–739, 743, 751, 852, 854, 1003, 1005, 1009–1014, 1016, 1019–1023, 1025, 1137–1138, 1140, 1191–1192, 1327, 1375–1376, 1492–1494, 1553, 1723, 1877, 1879
packages/core/agent_framework/_workflows
_agent_executor.py	166	22	86%	98, 146, 164–165, 216–217, 219–220, 252–254, 262–264, 274–276, 278, 282, 286, 290–291
_agent_utils.py	3	0	100%
_workflow_builder.py	276	37	86%	246, 522, 621, 628–629, 730, 733, 738, 740, 747, 750–754, 756, 818, 893, 896, 956–957, 1116, 1129, 1143–1150, 1152, 1155, 1157–1159, 1167
packages/orchestrations/agent_framework_orchestrations
_concurrent.py	193	30	84%	52, 61–62, 70–71, 90–91, 96, 123, 128, 133–134, 140, 162, 172, 179, 347, 350, 378, 434, 446, 485, 487–488, 490, 502–503, 508, 530, 534
_group_chat.py	294	39	86%	173, 336, 343, 372, 383–384, 390, 395, 411, 438–443, 445, 478–481, 483, 488–492, 656, 661, 675, 756, 762, 808, 828, 903–904, 938, 957, 976, 986
_handoff.py	382	57	85%	104–105, 107, 136–137, 159–169, 171, 173, 175, 180, 280, 334, 359, 387, 395–396, 410, 461–462, 494, 541–543, 730, 737, 742, 829, 832, 841–844, 854, 859, 866, 872–875, 910, 915, 1112, 1115, 1123, 1141, 1148, 1223
_magentic.py	617	90	85%	67–76, 81, 85–96, 261, 272, 276, 296, 357, 366, 368, 410, 427, 436–437, 439–441, 443, 454, 596, 598, 638, 686, 722–724, 726, 734–737, 741–744, 805–808, 899, 905, 911, 953, 991, 1023, 1040, 1051, 1108–1109, 1113–1115, 1139, 1163–1164, 1177, 1193, 1215, 1263–1264, 1302–1303, 1462, 1471, 1474, 1479, 1875, 1930, 1945, 1974
_orchestration_request_info.py	54	0	100%
_sequential.py	114	14	87%	74, 167, 185, 196, 202, 239, 241–242, 244, 256–257, 262, 284, 288
TOTAL	16583	2024	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3912	225 💤	0 ❌	0 🔥	1m 6s ⏱️

[Copilot]

Pull request overview

This pull request implements a breaking change that renames the AgentProtocol to AgentLike throughout the Python codebase to avoid confusion with communication protocols like the A2A protocol. The renaming is comprehensive and affects the core protocol definition, all type annotations, imports, documentation, error messages, and test files.

Changes:

• Renamed the core AgentProtocol protocol class to AgentLike in agent_framework/_agents.py
• Updated all type annotations, imports, and isinstance checks across packages and samples
• Updated documentation, docstrings, comments, error messages, and test files to reflect the new name

Reviewed changes

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

Show a summary per file

File	Description
python/packages/core/agent_framework/_agents.py	Core protocol definition renamed from AgentProtocol to AgentLike with updated exports
python/packages/core/agent_framework/_middleware.py	Updated TypeVar and type annotations for agent middleware
python/packages/core/agent_framework/observability.py	Updated TypeVar bound for agent telemetry
python/packages/core/agent_framework/_workflows/*.py	Updated all workflow builder and executor type annotations
python/packages/orchestrations/agent_framework_orchestrations/*.py	Updated all orchestration builder type annotations and error messages
python/packages/durabletask/agent_framework_durabletask/*.py	Updated durable task agent types and docstrings
python/packages/devui/agent_framework_devui/*.py	Updated dev UI agent types
python/packages/declarative/agent_framework_declarative/_workflows/_factory.py	Updated workflow factory agent types
python/packages/azurefunctions/agent_framework_azurefunctions/*.py	Updated Azure Functions agent types and docstrings
python/packages/ag-ui/agent_framework_ag_ui/*.py	Updated AG-UI agent types
python/packages/chatkit/README.md	Updated documentation reference
python/packages/core/AGENTS.md	Updated architecture documentation
python/samples/**/*.py	Updated all sample code comments and type hints
python/packages//tests/**/.py	Updated all test files including class names, docstrings, and assertions

[moonbox3]

Are there existing protocols in well-known Python packages with the *Like suffix? It really doesn't sit well with me. See my other ideas here: #3096 (comment).

[dmytrostruk]

Are there existing protocols in well-known Python packages with the *Like suffix? It really doesn't sit well with me. See my other ideas here: #3096 (comment).

@moonbox3 There is os.PathLike, but it's not a protocol, it's abstract base class:
https://docs.python.org/3/library/os.html#os.PathLike

I'm not sure about the alternatives you proposed in the issue. Maybe we can make it simply Agent or is that too generic? I think if we don't come up with better name, we can also leave it as AgentProtocol. cc: @eavanvalkenburg

[eavanvalkenburg]

The problem with AgentProtocol is that it overlaps with protocols in the agent space like A2A and mcp, so I do think AgentLike is the best alternative, and indeed PathLike is a good comparison

[eavanvalkenburg]

And I would prefer to use Agent for a actual implementation because otherwise people would expect to be able to use it, I'm not opposed to ranking ChatAgent to Agent 😉

[moonbox3]

The problem with AgentProtocol is that it overlaps with protocols in the agent space like A2A and mcp, so I do think AgentLike is the best alternative, and indeed PathLike is a good comparison

Following Python's stdlib (SupportsFloat, SupportsClose) and typing spec examples, SupportsAgentChat seems like the best.

[eavanvalkenburg]

Then it should be SupportsAgentRun, because the whole point is that its generic and doesn't care what kind of agent it is. And Chat is generic over the type of content in it, so I would hesitate to Chat part of this, having said that maybe we need to make ChatMessage -> Message as well...

[moonbox3]

Yes, SupportsAgentRun is good, too.