Python: [BREAKING]: Introducing Options as TypedDict and Generic

[eavanvalkenburg]

Motivation and Context

This PR makes a major overhaul of the way you can supply options to your chat clients, it leverages a TypedDict called ChatOptions for all the common options and derived classes from there for each provider. It leverages Generics to allow a developer to create specific Options and still get type-checking and IDE autocomplete for those.

For instance, when you want to use reasoning models with the OpenAI Chat Completion API, you could do this:

class OpenAIReasoningChatOptions(OpenAIChatOptions, total=False):
    """Chat options for OpenAI reasoning models (o1, o3, o4-mini, etc.)."""

    # Reasoning-specific parameters
    reasoning_effort: Literal["none", "minimal", "low", "medium", "high", "xhigh"]

    # Unsupported parameters for reasoning models (override with None)
    temperature: None
    top_p: None
    frequency_penalty: None
    presence_penalty: None
    logit_bias: None
    logprobs: None
    top_logprobs: None
    stop: None  # Not supported for o3 and o4-mini

# and then use them with the client:
client = OpenAIChatClient[OpenAIReasoningChatOptions]()
response = await client.get_response(
        "What is 2 + 2?",
        options={
            "model_id": "o3",
            "max_tokens": 100,
            "allow_multiple_tool_calls": True,
            # OpenAI-specific options work:
            "reasoning_effort": "medium",
            # Unsupported options are caught by type checker:
            "temperature": 0.7, <- would raise a flag in the IDE for a unsupported key
        },
    )
# or an agent
agent = ChatAgent[OpenAIReasoningChatOptions](
        chat_client=OpenAIChatClient(),
        # Options can be set at construction time
        default_options={ <- has type: OpenAIReasoningChatOptions
            "model_id": "o3",
            "max_tokens": 100,
            "allow_multiple_tool_calls": True,
            # OpenAI-specific options work:
            "reasoning_effort": "medium",
        },
)

This makes it very easy to leverage the latest and greatest options from different providers without needing code changes in our codebase on day 1 to support.

The rest of the setup is described in the included ADR.

Addresses item 10 from: #2902
Addresses item a part of item 5 from: #3096

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 pull request introduces a major breaking change that refactors the chat options system from a class-based ChatOptions to a TypedDict-based approach with generic type support. The changes enable:

1. Type-safe, IDE-autocomplete-friendly options using TypedDict
2. Generic support allowing custom provider-specific options without code changes
3. Runtime extensibility for new provider parameters
4. Consistent parameter passing via options dict instead of mixed kwargs and ChatOptions objects

Key Changes:

• Converted ChatOptions from a Pydantic-like class to a TypedDict
• Changed chat_options parameter to options (dict) throughout the codebase
• Introduced provider-specific TypedDict options (OpenAIChatOptions, OllamaChatOptions, etc.)
• Added Generic[TOptions] to all chat clients and agents
• Updated all samples, tests, and middleware to use the new dict-based approach

Reviewed changes

Copilot reviewed 100 out of 101 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/_types.py	Core ChatOptions refactored from class to TypedDict with utility functions
python/packages/core/agent_framework/_clients.py	BaseChatClient made generic over TOptions
python/packages/core/agent_framework/_agents.py	ChatAgent updated to use dict-based options
python/packages/core/agent_framework/openai/*.py	OpenAI clients updated with OpenAIChatOptions, OpenAIResponsesOptions
python/packages/core/agent_framework/azure/*.py	Azure clients updated with provider-specific options
python/packages/ollama/agent_framework_ollama/*.py	Ollama client updated with OllamaChatOptions
python/packages/foundry_local/*.py	Foundry Local client updated with options support
python/packages/core/agent_framework/_middleware.py	Middleware updated to work with dict-based options
python/packages/core/agent_framework/observability.py	Observability updated for dict-based options
python/samples/**/*.py	All samples updated to use new options parameter
python/packages//tests/**/.py	All tests updated to use dict-based options

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/a2a/agent_framework_a2a
_agent.py	139	7	94%	354–355, 392–393, 422–424
packages/ag-ui/agent_framework_ag_ui
_client.py	148	11	92%	39, 105–108, 111, 257, 287, 442–444
_orchestrators.py	359	46	87%	104, 113, 180, 413, 468–470, 479–480, 488, 490–492, 496, 505, 538, 540–542, 544–547, 549, 551–552, 554, 556–561, 635–637, 641–646, 690–692, 695
_types.py	33	1	96%	11
packages/ag-ui/agent_framework_ag_ui/_orchestration
_tooling.py	56	10	82%	30–32, 42–46, 57–58
packages/anthropic/agent_framework_anthropic
_chat_client.py	352	143	59%	63, 372, 395, 397, 410, 432–435, 485–486, 495, 497–498, 503, 520–521, 561, 576, 580–581, 600–601, 607, 616, 618, 622–623, 664–666, 668, 681–682, 689–691, 695–697, 701–704, 715, 717, 739, 749, 771–777, 784–785, 793–794, 803–806, 813–814, 820–821, 827–828, 834, 842–844, 848, 855–856, 862–863, 869–870, 876, 885–888, 895–896, 913, 920–921, 938, 958, 960, 969–970, 976, 999–1000, 1006–1007, 1016–1027, 1033–1040, 1046–1053, 1059–1069, 1075–1078
packages/azure-ai/agent_framework_azure_ai
_chat_client.py	466	80	82%	384, 643–644, 646, 649, 652, 655–660, 663, 665, 673, 685–687, 691, 694–695, 703–706, 716, 724–727, 729–730, 732–733, 740, 748–749, 757–758, 763–764, 768–775, 780–781, 789, 795, 803–805, 808, 830–831, 951, 981, 994–998, 1037–1039, 1042–1043, 1084–1089, 1137, 1146, 1172
_client.py	191	43	77%	242–245, 250, 253–256, 261, 264–265, 268, 275, 314, 316–319, 321, 419, 437–440, 483, 519–522, 527, 529–530, 532–540, 542
packages/azurefunctions/agent_framework_azurefunctions
_entities.py	181	21	88%	137, 177–178, 229, 237, 242–243, 270–271, 280, 287, 298, 304–305, 324–325, 395, 427–429, 431
_orchestration.py	112	12	89%	109–110, 114, 354, 359–366
packages/chatkit/agent_framework_chatkit
_converter.py	135	47	65%	37, 120, 125, 173, 175, 345, 398, 400, 419–421, 423, 441, 443, 445, 448, 460, 470, 488, 508–532, 534–536
packages/core/agent_framework
_agents.py	321	57	82%	51, 90, 96, 99, 102, 384, 445–447, 493, 547, 565, 702, 871, 874–876, 993–996, 998, 1001–1003, 1104, 1145, 1147, 1156–1161, 1167, 1169, 1179–1180, 1187, 1189–1190, 1198–1202, 1210–1211, 1213, 1218, 1220, 1254, 1299–1300, 1302, 1304, 1315
_clients.py	55	5	90%	48, 273, 317, 445, 447
_middleware.py	402	11	97%	803, 819, 866–867, 1072–1073, 1118, 1268, 1498, 1553–1554
_tools.py	730	81	88%	217, 263, 314, 316, 344, 514, 546–547, 649, 651, 671, 689, 703, 715, 720, 722, 729, 762, 818–820, 861, 885–911, 946, 956, 1140, 1476, 1554–1558, 1679, 1681, 1748, 1843, 1849, 1893–1894, 1907–1908, 1955, 2041, 2082–2083, 2111–2113, 2155–2156, 2166, 2223–2224, 2231–2232
_types.py	1039	131	87%	137, 139, 141, 143, 145, 147, 154–157, 175–176, 313, 315, 322, 341, 381, 427–428, 464, 614, 728–729, 731, 756, 763, 780–782, 867, 872–873, 875, 882–883, 885, 912, 921, 924–926, 931–932, 939, 943–945, 1101, 1190–1193, 1201–1202, 1293, 1474, 1480, 1875, 1891, 1893–1900, 1929, 1962–1964, 1970–1971, 2032, 2287, 2292, 2296, 2300, 2478–2480, 2492, 2531, 2576–2581, 2603, 2608, 3067, 3153–3155, 3228, 3239–3240, 3414, 3418, 3431, 3534–3536, 3539–3541, 3545, 3550, 3554, 3612, 3620–3622, 3672–3673, 3711, 3713, 3729, 3733–3735, 3737, 3748–3749, 3752–3756, 3762
observability.py	621	148	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, 1284, 1364–1366, 1438–1440, 1604, 1607, 1666, 1731–1734, 1748, 1750, 1757, 1773, 1776, 1836, 1852, 1856, 1990, 1992
packages/core/agent_framework/_workflows
_agent_executor.py	162	21	87%	26, 93, 111, 145, 161–162, 213–214, 216–217, 248–250, 260–262, 264, 268, 272, 276–277
_function_executor.py	61	4	93%	88, 94, 100, 117
_group_chat.py	600	107	82%	113, 149, 160, 384–394, 413, 440–441, 446, 508, 522, 529, 533–535, 538, 590–591, 593–595, 619–620, 676–685, 694–695, 698, 743, 757–759, 763, 765–769, 774, 776, 782, 786–788, 793–798, 804, 819, 842, 851, 874, 883, 888–889, 1051, 1070, 1074, 1128, 1178, 1196, 1204, 1229–1231, 1470, 1476, 1639, 1653, 1720–1721, 1723–1724, 1726, 1728, 1730–1731, 1967, 2039–2042, 2052, 2063, 2072–2074
_handoff.py	618	142	77%	63, 76–78, 85–86, 88, 90, 207, 215–220, 223–224, 238, 243, 262–265, 274–276, 287, 290, 300–311, 313, 319, 325, 360, 376, 378, 381, 383, 432, 541, 550–555, 557–558, 569, 586, 604, 619, 631, 653, 665–667, 673, 716–718, 721–724, 726–728, 1090, 1095, 1099, 1104, 1179, 1189, 1282, 1285, 1301, 1306, 1318, 1324–1327, 1370–1371, 1510, 1792, 1804, 1827, 1833, 1842, 1846, 1851, 1871, 1893, 1904, 1916, 1949, 1960, 1964, 1966–1970, 1986–1988, 1990–1997, 1999–2001, 2003–2004, 2006, 2008, 2028–2034, 2036, 2042
_magentic.py	1003	340	66%	47, 52, 74–83, 88, 92–103, 276, 281, 300, 302, 318, 326–335, 485, 489, 503, 509, 524, 604, 617, 634, 643–644, 646–648, 650, 661, 799–803, 808, 847, 894, 930–932, 934, 942–945, 949–952, 1086–1087, 1104, 1106–1107, 1115, 1151, 1160–1162, 1182, 1239, 1259, 1262, 1294, 1297, 1301–1302, 1315, 1325–1329, 1335, 1361–1365, 1373–1377, 1381–1382, 1385–1390, 1396–1398, 1401–1402, 1406–1407, 1418–1419, 1421–1422, 1427–1429, 1433–1434, 1436–1437, 1441–1442, 1444–1448, 1452–1454, 1458–1459, 1467, 1475, 1490, 1502, 1514–1517, 1540–1547, 1549–1552, 1562–1563, 1572–1573, 1578–1580, 1611, 1637, 1651, 1667, 1683, 1755, 1767–1768, 1800, 1836, 1841–1842, 1844, 1848–1850, 1881–1883, 1889–1891, 1894–1896, 1898, 1900, 1904, 1908, 1911, 1916, 1919–1924, 1927, 1929, 1934, 1938, 1941–1942, 1944–1946, 1949, 1953, 1958, 1961, 1966–1967, 2027–2028, 2033, 2037, 2039–2043, 2046–2048, 2051, 2054, 2061–2063, 2077, 2082–2083, 2310–2311, 2490–2491, 2493, 2507, 2512, 2515, 2571, 2582, 2593–2595, 2608–2609, 2614, 2627–2630, 2645–2647, 2662–2669, 2671, 2674–2675, 2677–2678, 2686, 2694–2695, 2697–2699, 2701–2704, 2708–2716, 2720–2721, 2724–2728, 2730–2731, 2733–2736, 2738–2741, 2743–2745, 2747–2748, 2750–2752, 2768–2771, 2783–2786, 2799–2802, 2806
packages/core/agent_framework/azure
_assistants_client.py	40	0	100%
_chat_client.py	77	4	94%	279, 281, 294–295
_responses_client.py	38	6	84%	137, 160, 187–190
packages/core/agent_framework/openai
_assistants_client.py	275	37	86%	61, 354, 368, 371, 373–374, 377, 380, 383–384, 395, 420, 422, 424, 426, 428, 433, 436, 439, 443, 454, 539, 558–559, 562, 570, 620, 645, 659–660, 662, 694–697, 749, 766
_chat_client.py	261	54	79%	53, 171–172, 176, 196, 206–207, 209, 220, 226, 228, 237, 242, 247, 254–256, 263, 268–269, 271, 290, 310, 329, 343, 348–362, 369–371, 446, 452, 456, 459, 461, 463, 469, 483–484, 490, 506
_responses_client.py	557	103	81%	268, 273, 275–276, 287, 305, 313, 316–323, 325, 330, 336, 340, 355, 358–359, 361, 398, 428, 472–473, 495, 500, 556, 559, 572, 581, 594, 645, 724, 729, 733–735, 739–740, 763, 778–779, 783–785, 832, 852–853, 866–867, 883–884, 973–974, 983–984, 1015–1016, 1032, 1034, 1108–1116, 1139–1145, 1164, 1182–1183, 1192, 1197–1199, 1205–1206, 1219, 1234, 1270–1271, 1273–1275, 1289–1290, 1293, 1295, 1305–1306, 1312, 1327
_shared.py	99	12	87%	62, 68–71, 149, 151, 158, 160, 173, 249, 273
packages/mem0/agent_framework_mem0
_provider.py	83	3	96%	164–165, 168
packages/purview/agent_framework_purview
_models.py	456	96	78%	220–224, 306, 308, 330, 332, 336, 363, 367, 414–419, 422–429, 440–443, 454–457, 487–488, 491, 493, 495–497, 531, 533, 535, 537, 539, 541, 543, 548–550, 552, 555, 561, 564, 603, 605, 607, 609, 611, 619, 621, 623, 625, 659, 663, 698, 700, 702, 706, 712, 714, 736–737, 762, 764, 766, 770, 789–791, 796–797, 830, 832, 844, 907, 910–914, 916, 944, 975, 977
TOTAL	17815	2922	83%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2627	154 💤	0 ❌	0 🔥	1m 0s ⏱️

[moonbox3]

We're tracking docs updated for this, too, right?