Python: Added Shell tool

[dmytrostruk]

Motivation and Context

• Added ShellTool support to the Python SDK with new shell_tool_call, shell_tool_result, and shell_command_output content types on Content, including factory methods and serialization
• Added get_shell_tool() factory on AnthropicClient that maps local shell functions to Anthropic's bash_20250124 API format, with tool name aliasing and updated bash_code_execution_tool_result parsing into shell content types
• Added get_shell_tool() factory on OpenAIResponsesClient supporting both hosted container shell and local shell execution, with response parsing for shell_call, local_shell_call, and shell_call_output item types in both sync and streaming modes
• Propagated additional_properties from function call content to function result content during auto-invocation
• Added samples for Anthropic local shell, OpenAI hosted shell, and OpenAI local shell with user confirmation prompts

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/anthropic/agent_framework_anthropic
_chat_client.py	412	37	91%	427, 430, 511, 598, 600, 743–744, 818, 848–849, 892–894, 896, 909–910, 917–919, 923–925, 929–932, 1046, 1056, 1108, 1229, 1256–1257, 1274, 1287, 1300, 1325–1326
packages/core/agent_framework
_agents.py	342	43	87%	435, 439, 491, 856, 892, 908, 991–994, 1055–1057, 1178, 1194, 1196, 1209, 1215, 1251, 1253, 1262–1267, 1272, 1274, 1280–1281, 1288, 1290–1291, 1299–1300, 1303–1305, 1313–1314, 1316, 1321, 1323
_tools.py	878	91	89%	167–168, 327, 329, 347–349, 356, 374, 388, 395, 402, 418, 420, 427, 464, 489, 493, 510–512, 559–561, 583, 637, 659, 722–728, 764, 775–786, 808–810, 815, 819, 833–835, 874, 943, 953, 963, 1019, 1050, 1069, 1352, 1410, 1430, 1506–1510, 1633, 1637, 1661, 1687, 1689, 1705, 1707, 1792, 1822, 1842, 1844, 1897, 1960, 2151–2152, 2200, 2268–2269, 2327, 2332, 2339
_types.py	1041	84	91%	59, 68–69, 123, 128, 147, 149, 153, 157, 159, 161, 163, 181, 185, 211, 233, 238, 243, 247, 277, 653–654, 1131, 1201, 1218, 1236, 1259, 1269, 1286–1287, 1289, 1307–1308, 1310, 1317–1318, 1320, 1355, 1366–1367, 1369, 1407, 1634, 1686, 1777–1782, 1804, 1809, 1975, 1987, 2239, 2260, 2355, 2584, 2791, 2861, 2873, 2891, 3089–3091, 3094–3096, 3100, 3105, 3109, 3193–3195, 3224, 3278, 3297–3298, 3301–3305, 3311
packages/core/agent_framework/openai
_assistants_client.py	324	35	89%	419, 421, 423, 426, 430–431, 434, 437, 442–443, 445, 448–450, 455, 466, 491, 493, 495, 497, 499, 504, 507, 510, 514, 525, 726, 812, 815, 844, 881–884, 954
_responses_client.py	800	130	83%	303–306, 310–311, 314–315, 321–322, 327, 340–346, 367, 375, 398, 495, 497, 594, 649, 653, 655, 657, 659, 727, 741, 821, 831, 836, 879, 958, 975, 988, 1049, 1140, 1145, 1149–1151, 1155–1156, 1200, 1229, 1235, 1245, 1251, 1256, 1262, 1267–1268, 1329, 1351–1352, 1367–1368, 1386–1387, 1428–1431, 1593, 1631–1632, 1648, 1650, 1730–1738, 1857, 1912, 1927, 1947–1957, 1970, 1981–1985, 1999, 2009–2020, 2029, 2061–2064, 2072–2073, 2075–2077, 2091–2093, 2103–2104, 2110, 2125
TOTAL	22458	2800	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4548	25 💤	0 ❌	0 🔥	1m 21s ⏱️

[Copilot]

Pull request overview

This pull request implements shell command execution capabilities for the Agent Framework across OpenAI and Anthropic providers. The implementation adds a new ShellTool class that extends FunctionTool, along with shell-specific content types for structured representation of command execution and results. The PR enables both hosted shell execution (in OpenAI's managed containers) and local shell execution (on the developer's machine) with provider-specific API mappings.

Changes:

• Introduced ShellTool class and @shell_tool decorator for creating shell command execution tools with provider-specific configuration support via additional_properties
• Added three shell content types (shell_tool_call, shell_tool_result, shell_command_output) with factory methods and serialization support
• Implemented OpenAI Responses API integration with get_hosted_shell_tool() for managed container execution and parsing logic for shell_call/shell_call_output
• Integrated Anthropic bash tool support by detecting ShellTool instances and mapping them to bash_20250124 API format, with updated result parsing to use shell content types
• Provided three sample implementations demonstrating OpenAI hosted shell, OpenAI local shell with user confirmation, and Anthropic local shell execution

Reviewed changes

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

Show a summary per file

File	Description
python/packages/core/agent_framework/_tools.py	Adds ShellTool class extending FunctionTool and @shell_tool decorator with overloads for convenient shell tool creation
python/packages/core/agent_framework/_types.py	Adds shell content type definitions (shell_tool_call, shell_tool_result, shell_command_output) with factory methods and serialization support
python/packages/core/agent_framework/__init__.py	Exports ShellTool and shell_tool to public API
python/packages/core/agent_framework/_agents.py	Reformats ternary expression for improved readability (formatting only)
python/packages/core/agent_framework/openai/_responses_client.py	Implements get_hosted_shell_tool() method and parsing logic for shell_call and shell_call_output in both sync and streaming modes
python/packages/anthropic/agent_framework_anthropic/_chat_client.py	Adds ShellTool detection in _prepare_tools_for_anthropic() to map to bash API format, updates bash result parsing to use shell content types instead of generic function_result
python/packages/core/tests/core/test_types.py	Adds comprehensive tests for shell content type creation, properties, and serialization roundtrip
python/packages/core/tests/openai/test_openai_responses_client.py	Adds tests for get_hosted_shell_tool() and shell_call/shell_call_output parsing including timeout scenarios
python/packages/anthropic/tests/test_anthropic_client.py	Adds tests for ShellTool to Anthropic bash format conversion and updates bash result parsing tests to verify shell content types, including error handling
python/packages/core/tests/workflow/test_workflow_kwargs.py	Formatting change to fit long line within reasonable length (formatting only)
python/packages/core/tests/workflow/test_agent_executor.py	Formatting change to fit function signature on one line (formatting only)
python/samples/02-agents/providers/openai/openai_responses_client_with_shell.py	Sample demonstrating OpenAI hosted shell tool with managed container execution
python/samples/02-agents/providers/openai/openai_responses_client_with_local_shell.py	Sample demonstrating local shell execution with OpenAI, including user confirmation prompts
python/samples/02-agents/providers/anthropic/anthropic_with_shell.py	Sample demonstrating local shell execution with Anthropic bash tool, including user confirmation prompts

[eavanvalkenburg]

I'm not convinced of this approach, I think adding a callable that executes to the get_hosted_shell_tool (maybe we should just call that get_shell_tool) and wrapping that runnable, setting the schema to the expected schema from the service and then having it act like a regular tool is maybe clearer and gives full discoverability to the user of what other settings they can set.

[eavanvalkenburg]

Couple of small comments left, but overall this looks much better, thanks for going through!