Python: Added Shell tool

[dmytrostruk]

Motivation and Context

• Added ShellTool class extending FunctionTool for local shell command execution, with @shell_tool decorator for convenient creation
• Added shell content types (shell_tool_call, shell_tool_result, shell_command_output) with factory methods and serialization support on Content
• Added get_hosted_shell_tool() on OpenAIResponsesClient for OpenAI's managed container shell, with response parsing for shell_call and shell_call_output (both sync and streaming)
• Added ShellTool detection in Anthropic's _prepare_tools_for_anthropic to map to bash_20250124 API format, with bash_code_execution_tool_result parsing into shell content types
• Provider-specific configuration (e.g. Anthropic tool type version) passed via additional_properties
• 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	387	35	90%	458, 545, 547, 690–691, 763, 784–785, 828–830, 832, 845–846, 853–855, 859–861, 865–868, 981, 991, 1043, 1164, 1191–1192, 1209, 1222, 1235, 1260–1261
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	888	97	89%	166–167, 322, 324, 342–344, 351, 369, 383, 390, 397, 413, 415, 422, 459, 484, 488, 505–507, 554–556, 578, 632, 654, 717–723, 759, 770–781, 803–805, 810, 814, 828–830, 869, 938, 948, 958, 1014, 1045, 1064, 1386–1389, 1397, 1399, 1483, 1540, 1560, 1631–1635, 1757, 1761, 1785, 1811, 1813, 1829, 1831, 1916, 1946, 1966, 1968, 2021, 2084, 2275–2276, 2324, 2392–2393, 2451, 2456, 2463
_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, 1124, 1194, 1211, 1229, 1252, 1262, 1279–1280, 1282, 1300–1301, 1303, 1310–1311, 1313, 1348, 1359–1360, 1362, 1400, 1627, 1679, 1770–1775, 1797, 1802, 1968, 1980, 2232, 2253, 2348, 2577, 2784, 2854, 2866, 2884, 3082–3084, 3087–3089, 3093, 3098, 3102, 3186–3188, 3217, 3271, 3290–3291, 3294–3298, 3304
packages/core/agent_framework/openai
_responses_client.py	693	108	84%	293–296, 300–301, 304–305, 311–312, 317, 330–336, 357, 365, 388, 557, 612, 616, 618, 620, 622, 740, 750, 755, 798, 877, 894, 907, 968, 1059, 1064, 1068–1070, 1074–1075, 1098, 1167, 1189–1190, 1205–1206, 1224–1225, 1266–1269, 1426–1427, 1443, 1445, 1524–1532, 1651, 1706, 1721, 1741–1749, 1760–1771, 1780, 1812–1815, 1823–1824, 1826–1828, 1842–1844, 1854–1855, 1861, 1876
TOTAL	22305	2783	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4728	247 💤	0 ❌	0 🔥	1m 20s ⏱️

[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