Python: [BREAKING]: Introducing Options as TypedDict and Generic (#3140)

* WIP typeddict for options

* updated all clients and ChatAgents

* updated everything

* added ADR

* fix mypy

* proper typevar imports

* fixed import

* fixed other imports

* slight update in the sample

* updated from feedback

* fixes

* fixed missing covariants and test fixes

* fixed typing

* updated anthropic thinking config

* ruff fixes

* fixed int tests

* fix tests and mypy

* updated integration tests

* updated docstring and test fix

* improved options handling in obser

* mypy fix

* updated a host of integration tests

* fix tests

* bedrock fix

python/samples/getting_started/agents/openai/openai_chat_client_with_runtime_json_schema.py

@@ -3,7 +3,7 @@
 import asyncio
 import json
 
-from agent_framework.openai import OpenAIChatClient
+from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions
 
 """
 OpenAI Chat Client Runtime JSON Schema Example
@@ -32,7 +32,7 @@ runtime_schema = {
 async def non_streaming_example() -> None:
     print("=== Non-streaming runtime JSON schema example ===")
 
-    agent = OpenAIChatClient().create_agent(
+    agent = OpenAIChatClient[OpenAIChatOptions]().create_agent(
         name="RuntimeSchemaAgent",
         instructions="Return only JSON that matches the provided schema. Do not add commentary.",
     )
@@ -42,7 +42,7 @@ async def non_streaming_example() -> None:
 
     response = await agent.run(
         query,
-        additional_chat_options={
+        options={
             "response_format": {
                 "type": "json_schema",
                 "json_schema": {
@@ -76,7 +76,7 @@ async def streaming_example() -> None:
     chunks: list[str] = []
     async for chunk in agent.run_stream(
         query,
-        additional_chat_options={
+        options={
             "response_format": {
                 "type": "json_schema",
                 "json_schema": {

python/samples/getting_started/agents/openai/openai_responses_client_reasoning.py

@@ -2,7 +2,7 @@
 
 import asyncio
 
-from agent_framework.openai import OpenAIResponsesClient
+from agent_framework.openai import OpenAIResponsesClient, OpenAIResponsesOptions
 
 """
 OpenAI Responses Client Reasoning Example
@@ -10,19 +10,20 @@ OpenAI Responses Client Reasoning Example
 This sample demonstrates advanced reasoning capabilities using OpenAI's gpt-5 models,
 showing step-by-step reasoning process visualization and complex problem-solving.
 
-This uses the additional_chat_options parameter to enable reasoning with high effort and detailed summaries.
-You can also set these options at the run level, since they are api and/or provider specific, you will need to lookup
-the correct values for your provider, since these are passed through as-is.
+This uses the default_options parameter to enable reasoning with high effort and detailed summaries.
+You can also set these options at the run level using the options parameter.
+Since these are api and/or provider specific, you will need to lookup
+the correct values for your provider, as they are passed through as-is.
 
 In this case they are here: https://platform.openai.com/docs/api-reference/responses/create#responses-create-reasoning
 """
 
 
-agent = OpenAIResponsesClient(model_id="gpt-5").create_agent(
+agent = OpenAIResponsesClient[OpenAIResponsesOptions](model_id="gpt-5").create_agent(
     name="MathHelper",
     instructions="You are a personal math tutor. When asked a math question, "
     "reason over how best to approach the problem and share your thought process.",
-    additional_chat_options={"reasoning": {"effort": "high", "summary": "detailed"}},
+    default_options={"reasoning": {"effort": "high", "summary": "detailed"}},
 )
 
 

python/samples/getting_started/agents/openai/openai_responses_client_with_runtime_json_schema.py

@@ -42,7 +42,7 @@ async def non_streaming_example() -> None:
 
     response = await agent.run(
         query,
-        additional_chat_options={
+        options={
             "response_format": {
                 "type": "json_schema",
                 "json_schema": {
@@ -76,7 +76,7 @@ async def streaming_example() -> None:
     chunks: list[str] = []
     async for chunk in agent.run_stream(
         query,
-        additional_chat_options={
+        options={
             "response_format": {
                 "type": "json_schema",
                 "json_schema": {