updated from feedback

eavanvalkenburg · eavanvalkenburg · commit e8ef41ad81fb · 2026-01-11T11:13:45.000+01:00
diff --git a/docs/decisions/0011-python-typeddict-options.md b/docs/decisions/0011-python-typeddict-options.md
@@ -108,8 +108,11 @@ response = await client.get_response(
 
 **Cons:**
 - More complex implementation
-- Requires TypeVar with default (Python 3.13+ or typing_extensions)
 - Some type: ignore comments needed for TypedDict field overrides
+- Minor: Requires TypeVar with default (Python 3.13+ or typing_extensions)
+
+> [NOTE!]
+> In .NET this is already achieved through overloads on the `GetResponseAsync` method for each provider-specific options class, e.g., `AnthropicChatOptions`, `OpenAIChatOptions`, etc. So this does not apply to .NET.
 
 ### Implementation Details
 
diff --git a/python/packages/ag-ui/agent_framework_ag_ui/_client.py b/python/packages/ag-ui/agent_framework_ag_ui/_client.py
@@ -81,7 +81,7 @@ def _unwrap_server_function_call_contents(contents: MutableSequence[Contents | d
     "TAGUIChatOptions",
     bound=TypedDict,  # type: ignore[valid-type]
     default="AGUIChatOptions",
-    contravariant=True,
+    covariant=True,
 )
 
 
diff --git a/python/packages/ag-ui/agent_framework_ag_ui/_types.py b/python/packages/ag-ui/agent_framework_ag_ui/_types.py
@@ -109,7 +109,7 @@ class AGUIChatOptions(ChatOptions, total=False):
 AGUI_OPTION_TRANSLATIONS: dict[str, str] = {}
 """Maps ChatOptions keys to AG-UI parameter names (protocol uses standard names)."""
 
-TAGUIChatOptions = TypeVar("TAGUIChatOptions", bound=TypedDict, default="AGUIChatOptions", contravariant=True)  # type: ignore[valid-type]
+TAGUIChatOptions = TypeVar("TAGUIChatOptions", bound=TypedDict, default="AGUIChatOptions", covariant=True)  # type: ignore[valid-type]
 
 
 # endregion
diff --git a/python/packages/ag-ui/agent_framework_ag_ui_examples/agents/document_writer_agent.py b/python/packages/ag-ui/agent_framework_ag_ui_examples/agents/document_writer_agent.py
@@ -2,8 +2,6 @@
 
 """Example agent demonstrating predictive state updates with document writing."""
 
-from typing import Any
-
 from agent_framework import ChatAgent, ChatClientProtocol, ai_function
 from agent_framework.ag_ui import AgentFrameworkAgent, DocumentWriterConfirmationStrategy
 
@@ -40,7 +38,7 @@ def write_document_local(document: str) -> str:
 )
 
 
-def document_writer_agent(chat_client: ChatClientProtocol[Any]) -> AgentFrameworkAgent:
+def document_writer_agent(chat_client: ChatClientProtocol) -> AgentFrameworkAgent:
     """Create a document writer agent with predictive state updates.
 
     Args:
diff --git a/python/packages/anthropic/agent_framework_anthropic/_chat_client.py b/python/packages/anthropic/agent_framework_anthropic/_chat_client.py
@@ -157,10 +157,10 @@ class AnthropicChatOptions(ChatOptions, total=False):
 
 TAnthropicOptions = TypeVar(
     "TAnthropicOptions",
-    bound=TypedDict,
+    bound=TypedDict,  # type: ignore[valid-type]
     default="AnthropicChatOptions",
-    contravariant=True,
-)  # type: ignore[valid-type]
+    covariant=True,
+)
 
 # Translation between framework options keys and Anthropic Messages API
 OPTION_TRANSLATIONS: dict[str, str] = {
diff --git a/python/packages/azure-ai/agent_framework_azure_ai/_chat_client.py b/python/packages/azure-ai/agent_framework_azure_ai/_chat_client.py
@@ -199,7 +199,7 @@ class AzureAIAgentOptions(ChatOptions, total=False):
     "TAzureAIAgentOptions",
     bound=TypedDict,  # type: ignore[valid-type]
     default="AzureAIAgentOptions",
-    contravariant=True,
+    covariant=True,
 )
 
 
@@ -262,14 +262,14 @@ def __init__(
 
                 # Using environment variables
                 # Set AZURE_AI_PROJECT_ENDPOINT=https://your-project.cognitiveservices.azure.com
-                # Set AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4
+                # Set AZURE_AI_MODEL_DEPLOYMENT_NAME=<model name>
                 credential = DefaultAzureCredential()
                 client = AzureAIAgentClient(credential=credential)
 
                 # Or passing parameters directly
                 client = AzureAIAgentClient(
                     project_endpoint="https://your-project.cognitiveservices.azure.com",
-                    model_deployment_name="gpt-4",
+                    model_deployment_name="<model name>",
                     credential=credential,
                 )
 
diff --git a/python/packages/azure-ai/agent_framework_azure_ai/_client.py b/python/packages/azure-ai/agent_framework_azure_ai/_client.py
@@ -54,7 +54,7 @@
     "TAzureAIClientOptions",
     bound=TypedDict,  # type: ignore[valid-type]
     default="OpenAIResponsesOptions",
-    contravariant=True,
+    covariant=True,
 )
 
 
diff --git a/python/packages/bedrock/agent_framework_bedrock/_chat_client.py b/python/packages/bedrock/agent_framework_bedrock/_chat_client.py
@@ -96,7 +96,7 @@ class BedrockChatOptions(ChatOptions, total=False):
 
     Keys:
         # Inherited from ChatOptions (mapped to Bedrock):
-        model_id: The Bedrock model identifier (e.g., 'anthropic.claude-3-sonnet-20240229-v1:0'),
+        model_id: The Bedrock model identifier,
             translates to ``modelId`` in Bedrock API.
         temperature: Sampling temperature,
             translates to ``inferenceConfig.temperature``.
@@ -177,7 +177,7 @@ class BedrockChatOptions(ChatOptions, total=False):
 }
 """Maps ChatOptions keys to Bedrock Converse API parameter names."""
 
-TBedrockChatOptions = TypeVar("TBedrockChatOptions", bound=TypedDict, default="BedrockChatOptions", contravariant=True)  # type: ignore[valid-type]
+TBedrockChatOptions = TypeVar("TBedrockChatOptions", bound=TypedDict, default="BedrockChatOptions", covariant=True)  # type: ignore[valid-type]
 
 
 # endregion
@@ -254,7 +254,7 @@ def __init__(
                 from agent_framework.bedrock import BedrockChatClient
 
                 # Basic usage with default credentials
-                client = BedrockChatClient(model_id="anthropic.claude-3-sonnet-20240229-v1:0")
+                client = BedrockChatClient(model_id="<model name>")
 
                 # Using custom ChatOptions with type safety:
                 from typing import TypedDict
@@ -265,9 +265,7 @@ class MyOptions(BedrockChatOptions, total=False):
                     my_custom_option: str
 
 
-                client: BedrockChatClient[MyOptions] = BedrockChatClient(
-                    model_id="anthropic.claude-3-sonnet-20240229-v1:0"
-                )
+                client = BedrockChatClient[MyOptions](model_id="<model name>")
                 response = await client.get_response("Hello", options={"my_custom_option": "value"})
         """
         try:
diff --git a/python/packages/core/agent_framework/_agents.py b/python/packages/core/agent_framework/_agents.py
@@ -57,7 +57,7 @@
 logger = get_logger("agent_framework")
 
 TThreadType = TypeVar("TThreadType", bound="AgentThread")
-TOptions = TypeVar("TOptions", bound=TypedDict, default="ChatOptions", contravariant=True)  # type: ignore[valid-type]
+TOptions = TypeVar("TOptions", bound=TypedDict, default="ChatOptions", covariant=True)  # type: ignore[valid-type]
 
 
 def _merge_options(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
@@ -673,6 +673,7 @@ def __init__(
                 provider-specific options including temperature, max_tokens, model_id,
                 tool_choice, and provider-specific options like reasoning_effort.
                 You can also create your own TypedDict for custom chat clients.
+                These can be overridden at runtime via the ``options`` parameter of ``run()`` and ``run_stream()``.
             tools: The tools to use for the request.
             kwargs: Any additional keyword arguments. Will be stored as ``additional_properties``.
 
diff --git a/python/packages/core/agent_framework/_clients.py b/python/packages/core/agent_framework/_clients.py
@@ -39,7 +39,7 @@
 TInput = TypeVar("TInput", contravariant=True)
 TEmbedding = TypeVar("TEmbedding")
 TBaseChatClient = TypeVar("TBaseChatClient", bound="BaseChatClient")
-TOptions = TypeVar("TOptions", bound=TypedDict, default="ChatOptions", contravariant=True)  # type: ignore[valid-type]
+TOptions = TypeVar("TOptions", bound=TypedDict, default="ChatOptions", covariant=True)  # type: ignore[valid-type]
 
 logger = get_logger()
 
diff --git a/python/packages/core/agent_framework/_workflows/_group_chat.py b/python/packages/core/agent_framework/_workflows/_group_chat.py
@@ -1480,16 +1480,20 @@ def set_manager(
             display_name = manager.id if isinstance(manager, Executor) else manager.name or "manager"
 
         # Enforce ManagerSelectionResponse for ChatAgent managers
-        if isinstance(manager, ChatAgent):
-            configured_format = manager.default_options.get("response_format")
-            if configured_format is None:
-                manager.default_options["response_format"] = ManagerSelectionResponse
-            elif configured_format is not ManagerSelectionResponse:
-                configured_format_name = getattr(configured_format, "__name__", str(configured_format))
-                raise ValueError(
-                    "Manager ChatAgent response_format must be ManagerSelectionResponse. "
-                    f"Received '{configured_format_name}' for manager '{display_name}'."
-                )
+        if (
+            isinstance(manager, ChatAgent)
+            and manager.default_options.setdefault("response_format", ManagerSelectionResponse)
+            != ManagerSelectionResponse
+        ):
+            configured_format_name = getattr(
+                manager.default_options.get("response_format"),
+                "__name__",
+                str(manager.default_options.get("response_format")),
+            )
+            raise ValueError(
+                "Manager ChatAgent response_format must be ManagerSelectionResponse. "
+                f"Received '{configured_format_name}' for manager '{display_name}'."
+            )
 
         self._manager_participant = manager
         self._manager_name = display_name
diff --git a/python/packages/core/agent_framework/azure/_chat_client.py b/python/packages/core/agent_framework/azure/_chat_client.py
@@ -202,13 +202,15 @@ def __init__(
 
                 # Using environment variables
                 # Set AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com
-                # Set AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=gpt-4
+                # Set AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=<model name>
                 # Set AZURE_OPENAI_API_KEY=your-key
                 client = AzureOpenAIChatClient()
 
                 # Or passing parameters directly
                 client = AzureOpenAIChatClient(
-                    endpoint="https://your-endpoint.openai.azure.com", deployment_name="gpt-4", api_key="your-key"
+                    endpoint="https://your-endpoint.openai.azure.com",
+                    deployment_name="<model name>",
+                    api_key="your-key",
                 )
 
                 # Or loading from a .env file
diff --git a/python/packages/core/agent_framework/observability.py b/python/packages/core/agent_framework/observability.py
@@ -1585,7 +1585,9 @@ def _get_span(
 
     Note: `attributes` must contain the `span_name_attribute` key.
     """
-    span = get_tracer().start_span(f"{attributes[OtelAttr.OPERATION]} {attributes[span_name_attribute]}")
+    operation = attributes.get(OtelAttr.OPERATION, "operation")
+    span_name = attributes.get(span_name_attribute, "unknown")
+    span = get_tracer().start_span(f"{operation} {span_name}")
     span.set_attributes(attributes)
     with trace.use_span(
         span=span,
@@ -1605,65 +1607,88 @@ def _get_instructions_from_chat_options(chat_options: Any) -> str | None:
     return None
 
 
+# Mapping configuration for extracting span attributes
+# Each entry: source_keys -> (otel_attribute_key, transform_func, check_options_first, default_value)
+# - source_keys: single key or list of keys to check (first non-None value wins)
+# - otel_attribute_key: target OTEL attribute name
+# - transform_func: optional transformation function, can return None to skip attribute
+# - check_options_first: whether to check options dict before kwargs
+# - default_value: optional default value if key is not found (use None to skip)
+OTEL_ATTR_MAP: dict[str | tuple[str, ...], tuple[str, Callable[[Any], Any] | None, bool, Any]] = {
+    "choice_count": (OtelAttr.CHOICE_COUNT, None, False, 1),
+    "operation_name": (OtelAttr.OPERATION, None, False, None),
+    "system_name": (SpanAttributes.LLM_SYSTEM, None, False, None),
+    "provider_name": (OtelAttr.PROVIDER_NAME, None, False, None),
+    "service_url": (OtelAttr.ADDRESS, None, False, None),
+    "conversation_id": (OtelAttr.CONVERSATION_ID, None, True, None),
+    "seed": (OtelAttr.SEED, None, True, None),
+    "frequency_penalty": (OtelAttr.FREQUENCY_PENALTY, None, True, None),
+    "max_tokens": (SpanAttributes.LLM_REQUEST_MAX_TOKENS, None, True, None),
+    "stop": (OtelAttr.STOP_SEQUENCES, None, True, None),
+    "temperature": (SpanAttributes.LLM_REQUEST_TEMPERATURE, None, True, None),
+    "top_p": (SpanAttributes.LLM_REQUEST_TOP_P, None, True, None),
+    "presence_penalty": (OtelAttr.PRESENCE_PENALTY, None, True, None),
+    "top_k": (OtelAttr.TOP_K, None, True, None),
+    "encoding_formats": (
+        OtelAttr.ENCODING_FORMATS,
+        lambda v: json.dumps(v if isinstance(v, list) else [v]),
+        True,
+        None,
+    ),
+    "agent_id": (OtelAttr.AGENT_ID, None, False, None),
+    "agent_name": (OtelAttr.AGENT_NAME, None, False, None),
+    "agent_description": (OtelAttr.AGENT_DESCRIPTION, None, False, None),
+    # Multiple source keys - checks model_id in options, then model in kwargs, then model_id in kwargs
+    ("model_id", "model"): (SpanAttributes.LLM_REQUEST_MODEL, None, True, None),
+    # Tools with validation - returns None if no valid tools
+    "tools": (
+        OtelAttr.TOOL_DEFINITIONS,
+        lambda tools: (
+            json.dumps(tools_dict)
+            if (tools_dict := __import__("agent_framework._tools", fromlist=["_tools_to_dict"])._tools_to_dict(tools))
+            else None
+        ),
+        True,
+        None,
+    ),
+    # Error type extraction
+    "error": (OtelAttr.ERROR_TYPE, lambda e: type(e).__name__, False, None),
+    # thread_id overrides conversation_id - processed after conversation_id due to dict ordering
+    "thread_id": (OtelAttr.CONVERSATION_ID, None, False, None),
+}
+
+
 def _get_span_attributes(**kwargs: Any) -> dict[str, Any]:
     """Get the span attributes from a kwargs dictionary."""
-    from ._tools import _tools_to_dict
-
     attributes: dict[str, Any] = {}
     # Support 'options' and 'chat_options' dict from chat clients and agents
-    options: dict[str, Any] = {}
-    if (opts := kwargs.get("options") or kwargs.get("chat_options")) and isinstance(opts, dict):
-        options = opts
-    if operation_name := kwargs.get("operation_name"):
-        attributes[OtelAttr.OPERATION] = operation_name
-    if choice_count := kwargs.get("choice_count", 1):
-        attributes[OtelAttr.CHOICE_COUNT] = choice_count
-    if system_name := kwargs.get("system_name"):
-        attributes[SpanAttributes.LLM_SYSTEM] = system_name
-    if provider_name := kwargs.get("provider_name"):
-        attributes[OtelAttr.PROVIDER_NAME] = provider_name
-    if model_id := options.get("model_id") or kwargs.get("model") or kwargs.get("model_id"):
-        attributes[SpanAttributes.LLM_REQUEST_MODEL] = model_id
-    if service_url := kwargs.get("service_url"):
-        attributes[OtelAttr.ADDRESS] = service_url
-    if conversation_id := options.get("conversation_id") or kwargs.get("conversation_id"):
-        attributes[OtelAttr.CONVERSATION_ID] = conversation_id
-    if seed := options.get("seed") or kwargs.get("seed"):
-        attributes[OtelAttr.SEED] = seed
-    if frequency_penalty := options.get("frequency_penalty") or kwargs.get("frequency_penalty"):
-        attributes[OtelAttr.FREQUENCY_PENALTY] = frequency_penalty
-    if max_tokens := options.get("max_tokens") or kwargs.get("max_tokens"):
-        attributes[SpanAttributes.LLM_REQUEST_MAX_TOKENS] = max_tokens
-    if stop := options.get("stop") or kwargs.get("stop"):
-        attributes[OtelAttr.STOP_SEQUENCES] = stop
-    if temperature := options.get("temperature") or kwargs.get("temperature"):
-        attributes[SpanAttributes.LLM_REQUEST_TEMPERATURE] = temperature
-    if top_p := options.get("top_p") or kwargs.get("top_p"):
-        attributes[SpanAttributes.LLM_REQUEST_TOP_P] = top_p
-    if presence_penalty := options.get("presence_penalty") or kwargs.get("presence_penalty"):
-        attributes[OtelAttr.PRESENCE_PENALTY] = presence_penalty
-    if top_k := options.get("top_k") or kwargs.get("top_k"):
-        attributes[OtelAttr.TOP_K] = top_k
-    if encoding_formats := options.get("encoding_formats") or kwargs.get("encoding_formats"):
-        attributes[OtelAttr.ENCODING_FORMATS] = json.dumps(
-            encoding_formats if isinstance(encoding_formats, list) else [encoding_formats]
-        )
-    if tools := options.get("tools") or kwargs.get("tools"):
-        tools_as_json_list = _tools_to_dict(tools)
-        if tools_as_json_list:
-            attributes[OtelAttr.TOOL_DEFINITIONS] = json.dumps(tools_as_json_list)
-    if error := kwargs.get("error"):
-        attributes[OtelAttr.ERROR_TYPE] = type(error).__name__
-    # agent attributes
-    if agent_id := kwargs.get("agent_id"):
-        attributes[OtelAttr.AGENT_ID] = agent_id
-    if agent_name := kwargs.get("agent_name"):
-        attributes[OtelAttr.AGENT_NAME] = agent_name
-    if agent_description := kwargs.get("agent_description"):
-        attributes[OtelAttr.AGENT_DESCRIPTION] = agent_description
-    if thread_id := kwargs.get("thread_id"):
-        # override if thread is set
-        attributes[OtelAttr.CONVERSATION_ID] = thread_id
+    options = kwargs.get("options", kwargs.get("chat_options"))
+    if options is not None and not isinstance(options, dict):
+        options = None
+
+    for source_keys, (otel_key, transform_func, check_options, default_value) in OTEL_ATTR_MAP.items():
+        # Normalize to tuple of keys
+        keys = (source_keys,) if isinstance(source_keys, str) else source_keys
+
+        value = None
+        for key in keys:
+            if check_options and options is not None:
+                value = options.get(key)
+            if value is None:
+                value = kwargs.get(key)
+            if value is not None:
+                break
+
+        # Apply default value if no value found
+        if value is None and default_value is not None:
+            value = default_value
+
+        if value is not None:
+            result = transform_func(value) if transform_func else value
+            # Allow transform_func to return None to skip attribute
+            if result is not None:
+                attributes[otel_key] = result
+
     return attributes
 
 
diff --git a/python/packages/core/agent_framework/openai/_chat_client.py b/python/packages/core/agent_framework/openai/_chat_client.py
@@ -104,7 +104,7 @@ class OpenAIChatOptions(ChatOptions, total=False):
     top_logprobs: int
 
 
-TOpenAIChatOptions = TypeVar("TOpenAIChatOptions", bound=TypedDict, default="OpenAIChatOptions", contravariant=True)  # type: ignore[valid-type]
+TOpenAIChatOptions = TypeVar("TOpenAIChatOptions", bound=TypedDict, default="OpenAIChatOptions", covariant=True)  # type: ignore[valid-type]
 
 OPTION_TRANSLATIONS: dict[str, str] = {
     "model_id": "model",
@@ -591,11 +591,11 @@ def __init__(
 
                 # Using environment variables
                 # Set OPENAI_API_KEY=sk-...
-                # Set OPENAI_CHAT_MODEL_ID=gpt-4
+                # Set OPENAI_CHAT_MODEL_ID=<model name>
                 client = OpenAIChatClient()
 
                 # Or passing parameters directly
-                client = OpenAIChatClient(model_id="gpt-4", api_key="sk-...")
+                client = OpenAIChatClient(model_id="<model name>", api_key="sk-...")
 
                 # Or loading from a .env file
                 client = OpenAIChatClient(env_file_path="path/to/.env")
@@ -609,7 +609,7 @@ class MyOptions(OpenAIChatOptions, total=False):
                     my_custom_option: str
 
 
-                client: OpenAIChatClient[MyOptions] = OpenAIChatClient(model_id="gpt-4o")
+                client: OpenAIChatClient[MyOptions] = OpenAIChatClient(model_id="<model name>")
                 response = await client.get_response("Hello", options={"my_custom_option": "value"})
         """
         try:
diff --git a/python/packages/devui/agent_framework_devui/_discovery.py b/python/packages/devui/agent_framework_devui/_discovery.py
diff --git a/python/packages/ollama/agent_framework_ollama/_chat_client.py b/python/packages/ollama/agent_framework_ollama/_chat_client.py

Original file line number	Diff line number	Diff line change
`@@ -81,7 +81,7 @@ def _unwrap_server_function_call_contents(contents: MutableSequence[Contents \| d`
`81`	`81`	`"TAGUIChatOptions",`
`82`	`82`	`bound=TypedDict, # type: ignore[valid-type]`
`83`	`83`	`default="AGUIChatOptions",`
`84`		`- contravariant=True,`
	`84`	`+ covariant=True,`
`85`	`85`	`)`
`86`	`86`
`87`	`87`
Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,7 @@`
`54`	`54`	`"TAzureAIClientOptions",`
`55`	`55`	`bound=TypedDict, # type: ignore[valid-type]`
`56`	`56`	`default="OpenAIResponsesOptions",`
`57`		`- contravariant=True,`
	`57`	`+ covariant=True,`
`58`	`58`	`)`
`59`	`59`
`60`	`60`