Python: [BREAKING] changed AIFunction to FunctionTool and @ai_function to @tool

[eavanvalkenburg]

Motivation and Context

Updated naming of AIFunction to FunctionTool
Also added a default to the generic arguments
And the decorator from @ai_function to @tool
Fixes: #3247 and #3368
Closes: #2902 (final point has a additional issue created for it)

Description

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
_client.py	140	11	92%	37, 88–92, 238, 268, 423–425
_utils.py	101	2	98%	257, 262
packages/anthropic/agent_framework_anthropic
_chat_client.py	362	151	58%	51, 362, 385, 387, 402, 424–427, 436, 438, 469–473, 475, 477–478, 480, 485–486, 488, 521–522, 531, 533–534, 539, 556–557, 599, 614, 618–619, 635, 644, 646, 650–651, 694–696, 698, 711–712, 719–721, 725–727, 731–734, 745, 747, 769, 779, 801–807, 814–815, 823–824, 832–835, 842–843, 849–850, 856–857, 863, 871–873, 877, 884–885, 891–892, 898–899, 905, 913–916, 923–924, 943, 950–951, 970, 992, 994, 1003–1004, 1010, 1032–1033, 1039–1040, 1049–1059, 1066–1072, 1079–1085, 1092–1101, 1108–1111
packages/azure-ai/agent_framework_azure_ai
_agent_provider.py	114	12	89%	118–119, 247, 440–442, 473–478
_chat_client.py	478	94	80%	377, 638–639, 641, 644, 647, 650–655, 658, 660, 668, 680–682, 686, 689–690, 698–701, 711, 719–722, 724–725, 727–728, 735, 743–744, 752–753, 758–759, 763–770, 775, 778, 786, 792, 800–802, 805, 827–828, 938, 940, 942, 957, 985, 998–1002, 1041–1043, 1046–1047, 1093–1099, 1121, 1147, 1156, 1165, 1167, 1172, 1181–1186, 1298
_project_provider.py	114	9	92%	128–129, 207, 305, 349, 382, 431–433
_shared.py	302	123	59%	105–106, 109–111, 114–119, 121, 152, 154, 156, 158, 203, 291–294, 297–299, 302–303, 313, 320–322, 348–357, 362, 410, 426–428, 430–447, 455–458, 463–464, 468–475, 480–481, 487–490, 492, 512–514, 517–518, 520, 532, 534–535, 538–541, 544, 546–547, 549–557, 559, 595, 597–600, 602, 608, 614, 618, 633, 636–637, 639
packages/core/agent_framework
_agents.py	305	53	82%	51, 90, 98, 101, 104, 406–408, 454, 637, 806, 809–811, 929–931, 936–938, 1039, 1080, 1082, 1091–1096, 1102, 1104, 1114–1115, 1122, 1124–1125, 1133–1137, 1145–1146, 1148, 1153, 1155, 1189, 1229, 1246–1247, 1249, 1251, 1262
_mcp.py	388	57	85%	112, 174, 183, 246, 254, 275, 365, 432, 467, 469, 473–474, 476–477, 480–481, 484–485, 531, 546, 564, 605, 711, 724–729, 751, 770, 773–775, 790–791, 797–799, 818, 827, 830–832, 847–848, 852–856, 873–877, 1017
_middleware.py	402	7	98%	805, 821, 868–869, 1074–1075, 1120
_serialization.py	105	15	85%	332–335, 347–348, 351–352, 357, 516, 532, 542, 554, 610, 613
_tools.py	768	85	88%	226, 272, 323, 325, 353, 523, 558–559, 661, 663, 683, 701, 715, 727, 732, 734, 741, 774, 830–832, 873, 895–923, 958, 966, 1207, 1544, 1631–1635, 1657–1658, 1774, 1776, 1842, 1934, 1940, 1982–1983, 1996–1997, 2040, 2124, 2162–2163, 2202–2204, 2242–2243, 2253, 2310–2311, 2318–2319
_types.py	947	132	86%	71, 94–95, 149, 154, 173, 175, 179, 183, 185, 187, 189, 206–207, 209–211, 213–214, 216–217, 219–220, 235–237, 239–242, 259, 264, 269, 273, 299, 303, 647–648, 1019, 1081, 1098, 1116, 1121, 1139, 1147–1149, 1166–1167, 1169, 1187–1188, 1190, 1197–1198, 1200, 1235, 1246–1247, 1249, 1268–1269, 1272–1281, 1284–1287, 1289, 1293, 1327, 1360, 1532, 1537, 1541, 1545, 1737, 1747, 1792, 1837–1842, 1864, 1869, 2228, 2237, 2373, 2461–2463, 2502, 2558, 2579, 2588, 2817–2819, 2822–2824, 2828, 2833, 2837, 2949–2951, 2979, 3015, 3033, 3037–3039, 3041, 3052–3053, 3056–3060, 3066
observability.py	625	144	76%	244, 312–317, 319, 321–322, 324, 326–328, 331–333, 338–339, 345–346, 352–353, 360, 362–364, 367–369, 374–375, 381–382, 388–389, 396, 433, 436, 439–441, 444, 447–448, 451–453, 455–457, 460, 547, 549, 631, 649–650, 652, 655, 663–664, 667–670, 672, 675–677, 680–681, 694–700, 702–711, 714–718, 721–724, 726–729, 732–733, 741, 842, 844, 869–871, 993, 995, 999–1004, 1006, 1009–1013, 1015, 1290, 1374–1376, 1449–1451, 1615, 1618, 1677, 1761, 1763, 1770, 1786, 1789, 1849, 1865, 1869, 2003, 2005
packages/core/agent_framework/_workflows
_agent.py	278	45	83%	56, 64–70, 98–99, 255, 311, 325, 338, 387–390, 396, 402, 406–407, 410–416, 420–421, 490, 497, 503–504, 515, 547, 554, 575, 584, 588, 590–592, 599
_const.py	6	0	100%
_handoff.py	386	59	84%	58, 110–111, 113, 142–143, 163–173, 175, 177, 179, 184, 284, 338, 363, 389, 397–398, 412, 461–462, 492, 539–541, 729, 736, 741, 828, 831, 840–843, 853, 858, 865, 871–874, 909, 914, 1104, 1117, 1120, 1128, 1146, 1153, 1228
_workflow.py	247	17	93%	88, 258–260, 262–263, 281, 309, 410, 687, 721, 726, 729, 748–750, 815
packages/core/agent_framework/openai
_assistant_provider.py	109	11	89%	153–154, 166, 291, 357, 472–477
_assistants_client.py	280	31	88%	60, 353, 367, 370, 372–373, 376, 379, 382–383, 394, 419, 421, 423, 425, 427, 432, 435, 438, 442, 453, 538, 623, 658, 695–698, 750, 767, 812
_chat_client.py	268	22	91%	44, 178–179, 183, 269, 276, 357–364, 366–369, 379, 464, 501, 517
_responses_client.py	560	64	88%	250, 255, 257–258, 269, 287, 295, 318, 380, 412, 437, 443, 461–462, 484, 489, 545, 559, 576, 589, 644, 723, 728, 732–734, 738–739, 762, 831, 853–854, 869–870, 888–889, 1020–1021, 1037, 1039, 1114–1122, 1170, 1225, 1240, 1276–1277, 1279–1281, 1295–1297, 1307–1308, 1314, 1329
_shared.py	132	15	88%	63, 69–72, 150, 152, 159, 161, 174, 250, 274, 338–339, 341
TOTAL	16177	2411	85%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3450	221 💤	0 ❌	0 🔥	1m 6s ⏱️

[Copilot]

Pull request overview

This PR implements a breaking change that renames AIFunction to FunctionTool and the @ai_function decorator to @tool. The changes are comprehensive and consistent across the entire codebase.

Changes:

• Renamed AIFunction class to FunctionTool throughout the codebase
• Renamed @ai_function decorator to @tool
• Updated serialization type identifier from "ai_function" to "function_tool"
• Added default type parameters to the generic FunctionTool[ArgsT, ReturnT] using TypeVarWithDefaults
• Fixed deepcopy issue with tools containing HTTP clients (addresses issue #3247)
• Updated all samples, tests, documentation, and package code consistently

Reviewed changes

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

Show a summary per file

File	Description
python/packages/core/agent_framework/_tools.py	Core rename from AIFunction to FunctionTool, added TypeVar defaults, updated type identifier
python/packages/core/agent_framework/_agents.py	Fixed deepcopy issue by shallow copying tools to avoid copying HTTP clients
python/packages/core/agent_framework/_types.py	Updated normalize_tools and validate_tools functions, proper variable naming to avoid shadowing
python/packages/core/agent_framework/_serialization.py	Updated documentation examples to use new naming
Various client implementations	Updated all pattern matches and type checks across OpenAI, Azure, Anthropic, Bedrock, Ollama clients
Test files	Comprehensive updates to all test files with consistent naming
Sample files	All samples updated to use new @tool decorator and FunctionTool class
Documentation	Updated README files and coding standards to reflect new naming

Comments suppressed due to low confidence (1)

python/packages/azure-ai/tests/test_provider.py:491

• This class does not call MCPTool.init during initialization. (MockMCPTool.init may be missing a call to a base class init)

class MockMCPTool(MCPTool):  # pyright: ignore[reportGeneralTypeIssues]

[giles17]

Believe this also fixes #3368

[droideronline]

@eavanvalkenburg @giles17 - Regarding #3368, the issue get resolved when instrumentation is disabled. I suspect
in _tools.py - self._invocation_duration_histogram = _default_histogram() to be the culprit.
when instrumentation is disabled, default histogram creates a No-op histogram but when Instrumentation is enabled, it create a histogram with Lock. Please have a look at this case as well. Thanks!

[TaoChenOSU]

Will this be accompanied by a documentation update PR?