Python: [BREAKING] Replace Hosted*Tool classes with tool methods by giles17 · Pull Request #3634 · microsoft/agent-framework

giles17 · 2026-02-03T04:29:41Z

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 · 2026-02-03T04:52:13Z

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.

Replace Hosted*Tool classes with client static factory methods

5e234ef

Copilot AI review requested due to automatic review settings February 3, 2026 04:29

markwallace-microsoft added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python lab labels Feb 3, 2026

Copilot started reviewing on behalf of giles17 February 3, 2026 04:30 View session

github-actions Bot changed the title ~~[BREAKING] Replace Hosted*Tool classes with client static factory methods~~ Python: [BREAKING] Replace Hosted*Tool classes with client static factory methods Feb 3, 2026

Copilot AI reviewed Feb 3, 2026

View reviewed changes

fixed failing test

2d8183d

giles17 added 3 commits February 2, 2026 21:17

mypy fix

7164800

mypy fix 2

6ba4cd5

declarative mypy fix

8528915

giles17 changed the title ~~Python: [BREAKING] Replace Hosted*Tool classes with client static factory methods~~ Python: [BREAKING] Replace Hosted*Tool classes with tool methods Feb 3, 2026

eavanvalkenburg reviewed Feb 3, 2026

View reviewed changes

giles17 added 6 commits February 3, 2026 15:30

addressed comments

25cee57

Merge branch 'main' into refactor-hosted-tools

b61f287

ToolProtocol removal

2850f33

Merge branch 'main' into refactor-hosted-tools

b524a41

fixed test

c63292c

agents mypy fix

10d260d

dmytrostruk approved these changes Feb 5, 2026

View reviewed changes

Merge branch 'main' into refactor-hosted-tools

26263f1

eavanvalkenburg reviewed Feb 6, 2026

View reviewed changes

giles17 added 6 commits February 6, 2026 14:29

merge conflict fix

c14d16c

fix failing tests

c80e106

mypy fix

f401744

Merge branch 'main' into refactor-hosted-tools

0f8ee5b

addressed comments

9808b1b

fixed tests

5356361

eavanvalkenburg approved these changes Feb 10, 2026

View reviewed changes

Merge branch 'main' into refactor-hosted-tools

d2496ec

giles17 enabled auto-merge February 10, 2026 20:21

eavanvalkenburg approved these changes Feb 10, 2026

View reviewed changes

giles17 added this pull request to the merge queue Feb 10, 2026