Python: [BREAKING] Replace Hosted*Tool classes with tool methods

[giles17]

Motivation and Context

This PR refactors hosted tool support from standalone Hosted*Tool classes to @staticmethod factory methods on the chat clients that support them. This is a breaking change that improves API discoverability and makes tool support explicit per client

Breaking Changes

Removed classes:

• HostedCodeInterpreterTool
• HostedWebSearchTool
• HostedImageGenerationTool
• HostedFileSearchTool
• HostedMCPTool

Migration:

# BEFORE (old API - removed)
from agent_framework import HostedCodeInterpreterTool, HostedWebSearchTool
tool = HostedCodeInterpreterTool()
search = HostedWebSearchTool(additional_properties={"user_location": {...}})

# AFTER (new API)
from agent_framework.openai import OpenAIResponsesClient

client = OpenAIResponsesClient()
tool = client.get_code_interpreter_tool()
search = client.get_web_search_tool(user_location={"city": "Seattle"})

#3586

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.

[Copilot]

Pull request overview

This PR implements a breaking change that refactors hosted tool support from standalone Hosted*Tool classes to static factory methods on chat clients. This improves API discoverability by making tool support explicit per client type.

Changes:

• Removed HostedCodeInterpreterTool, HostedWebSearchTool, HostedFileSearchTool, HostedImageGenerationTool, and HostedMCPTool classes
• Added static factory methods (get_code_interpreter_tool(), get_web_search_tool(), etc.) to relevant client classes
• Introduced protocol classes (SupportsCodeInterpreterTool, SupportsWebSearchTool, etc.) for runtime checking of tool support
• Updated all samples, tests, and documentation to use the new API

Reviewed changes

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

Show a summary per file

File	Description
python/packages/core/agent_framework/_clients.py	Added tool support protocol definitions
python/packages/core/agent_framework/openai/_chat_client.py	Added get_web_search_tool() static method
python/packages/core/agent_framework/openai/_assistants_client.py	Added get_code_interpreter_tool() and get_file_search_tool() static methods
python/packages/core/agent_framework/openai/_responses_client.py	Added static methods for all hosted tools (code interpreter, web search, file search, image generation, MCP)
python/packages/azure-ai/agent_framework_azure_ai/_client.py	Added Azure-specific get_mcp_tool() implementation
python/packages/anthropic/agent_framework_anthropic/_chat_client.py	Added static methods for Anthropic-supported tools
Multiple sample files	Updated to use new static factory methods instead of Hosted*Tool classes
Multiple test files	Updated test assertions to check for dict-based tools instead of class instances
python/packages/declarative/agent_framework_declarative/_loader.py	Updated to create dict-based tools directly

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/ag-ui/agent_framework_ag_ui
_utils.py	100	1	99%	74
packages/anthropic/agent_framework_anthropic
_chat_client.py	367	148	59%	444, 473, 505, 507, 522, 544–547, 556, 558, 595–599, 601, 603–604, 606, 611–612, 614, 647–648, 657, 659–660, 665, 682–683, 727, 750, 759, 761, 765–766, 809–811, 813, 826–827, 834–836, 840–842, 846–849, 860, 862, 884, 894, 916–922, 929–930, 938–939, 947–950, 957–958, 964–965, 971–972, 978, 986–988, 992, 999–1000, 1006–1007, 1013–1014, 1020, 1028–1031, 1038–1039, 1058, 1065–1066, 1085, 1107, 1109, 1118–1119, 1125, 1147–1148, 1154–1155, 1164–1174, 1181–1187, 1194–1200, 1207–1216, 1223–1226
packages/azure-ai/agent_framework_azure_ai
_agent_provider.py	117	3	97%	121–122, 250
_chat_client.py	476	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, 1466
_client.py	214	22	89%	373, 375, 424, 453–458, 501, 536, 538, 571, 779, 782, 785–786, 788–791, 840
_project_provider.py	116	6	94%	133–134, 212, 310, 354, 387
_shared.py	232	17	92%	107, 137, 221, 264, 276–278, 307, 309, 311, 315, 380, 411, 452, 459, 471, 490
packages/core/agent_framework
_agents.py	320	35	89%	474, 887, 924, 1024–1026, 1139, 1180, 1182, 1191–1196, 1202, 1204, 1214–1215, 1222, 1224–1225, 1233–1237, 1245–1246, 1248, 1253, 1255, 1289, 1329, 1349
_clients.py	73	3	95%	301, 502, 504
_mcp.py	392	53	86%	127, 189, 198, 261, 269, 290, 380, 447, 482, 484, 488–489, 491–492, 546, 561, 579, 620, 726, 739–744, 766, 787, 790–792, 807–808, 814–816, 835, 844, 847–849, 864–865, 869–873, 890–894, 1034
_memory.py	27	1	96%	154
_sessions.py	149	6	95%	196–199, 504, 518
_tools.py	724	82	88%	176–177, 300, 302, 319–321, 328, 346, 360, 372, 377, 379, 386, 419, 490–492, 533, 555–583, 618, 626, 867, 1119, 1176, 1180, 1259–1263, 1281, 1283–1284, 1396, 1400, 1450, 1452, 1468, 1470, 1534, 1561, 1618, 1686, 1865–1866, 1893, 1901, 1914, 1924–1925, 1960, 2016, 2048
_types.py	1045	96	90%	83, 92–93, 147, 152, 171, 173, 177, 181, 183, 185, 187, 205, 209, 235, 257, 262, 267, 271, 297, 301, 647–648, 1019, 1081, 1098, 1116, 1121, 1139, 1149, 1166–1167, 1169, 1187–1188, 1190, 1197–1198, 1200, 1235, 1246–1247, 1249, 1287, 1544, 1597, 1604, 1626, 1632, 1680, 1723–1728, 1750, 1755, 1921, 1933, 2176, 2185, 2206, 2301, 2526, 2733, 2803, 2815, 2822, 2833, 3037–3039, 3042–3044, 3048, 3053, 3057, 3169–3171, 3199, 3253, 3257–3259, 3261, 3272–3273, 3276–3280, 3286
packages/core/agent_framework/openai
_assistant_provider.py	111	11	90%	158–159, 171, 296, 362, 477–482
_assistants_client.py	278	35	87%	414, 416, 418, 421, 425–426, 429, 432, 437–438, 440, 443–445, 450, 461, 486, 488, 490, 492, 494, 499, 502, 505, 509, 520, 605, 690, 719, 756–759, 811, 828
_chat_client.py	271	22	91%	202, 232–233, 237, 351, 358, 439–446, 448–451, 461, 546, 583, 599
_responses_client.py	605	80	86%	292–295, 299–300, 303–304, 310–311, 316, 329–335, 356, 364, 387, 550, 553, 608, 612, 614, 616, 618, 694, 704, 709, 752, 811, 825, 842, 855, 910, 989, 994, 998–1000, 1004–1005, 1028, 1097, 1119–1120, 1135–1136, 1154–1155, 1286–1287, 1303, 1305, 1384–1392, 1487, 1542, 1557, 1593–1594, 1596–1598, 1612–1614, 1624–1625, 1631, 1646
_shared.py	129	16	87%	65, 71–74, 153, 155, 157, 164, 166, 179, 255, 279, 338–339, 341
TOTAL	16787	2110	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4006	225 💤	0 ❌	0 🔥	1m 11s ⏱️

[eavanvalkenburg]

Couple of notes, overall I think we will have to move to remove some additional pieces of from tools and streamline things even more, I would expect only the functionTool to be handled in the each clients prepare code, everything else should already be setup correctly.