Python: [BREAKING] Types API Review improvements (#3647)

* Replace Role and FinishReason classes with NewType + Literal

- Remove EnumLike metaclass from _types.py
- Replace Role class with NewType('Role', str) + RoleLiteral
- Replace FinishReason class with NewType('FinishReason', str) + FinishReasonLiteral
- Update all usages across codebase to use string literals
- Remove .value access patterns (direct string comparison now works)
- Add backward compatibility for legacy dict serialization format
- Update tests to reflect new string-based types

Addresses #3591, #3615

* Simplify ChatResponse and AgentResponse type hints (#3592)

- Remove overloads from ChatResponse.__init__
- Remove text parameter from ChatResponse.__init__
- Remove | dict[str, Any] from finish_reason and usage_details params
- Remove **kwargs from AgentResponse.__init__
- Both now accept ChatMessage | Sequence[ChatMessage] | None for messages
- Update docstrings and examples to reflect changes
- Fix tests that were using removed kwargs
- Fix Role type hint usage in ag-ui utils

* Remove text parameter from ChatResponseUpdate and AgentResponseUpdate (#3597)

- Remove text parameter from ChatResponseUpdate.__init__
- Remove text parameter from AgentResponseUpdate.__init__
- Remove **kwargs from both update classes
- Simplify contents parameter type to Sequence[Content] | None
- Update all usages to use contents=[Content.from_text(...)] pattern
- Fix imports in test files
- Update docstrings and examples

* Rename from_chat_response_updates to from_updates (#3593)

- ChatResponse.from_chat_response_updates → ChatResponse.from_updates
- ChatResponse.from_chat_response_generator → ChatResponse.from_update_generator
- AgentResponse.from_agent_run_response_updates → AgentResponse.from_updates

* Remove try_parse_value method from ChatResponse and AgentResponse (#3595)

- Remove try_parse_value method from ChatResponse
- Remove try_parse_value method from AgentResponse
- Remove try_parse_value calls from from_updates and from_update_generator methods
- Update samples to use try/except with response.value instead
- Update tests to use response.value pattern
- Users should now use response.value with try/except for safe parsing

* Add agent_id to AgentResponse and clarify author_name documentation (#3596)

- Add agent_id parameter to AgentResponse class
- Document that author_name is on ChatMessage objects, not responses
- Update ChatResponse docstring with author_name note
- Update AgentResponse docstring with author_name note

* Simplify ChatMessage.__init__ signature (#3618)

- Make contents a positional argument accepting Sequence[Content | str]
- Auto-convert strings in contents to TextContent
- Remove overloads, keep text kwarg for backward compatibility with serialization
- Update _parse_content_list to handle string items
- Update all usages across codebase to use new format: ChatMessage("role", ["text"])

* Allow Content as input on run and get_response

- Update prepare_messages and normalize_messages to accept Content
- Update type signatures in _agents.py and _clients.py
- Add tests for Content input handling

* Fix ChatMessage usage across packages and samples

Update all remaining ChatMessage(role=..., text=...) to use new
ChatMessage('role', ['text']) signature.

* Fix Role string usage and response format parsing

- Fix redis provider: remove .value access on string literals
- Fix durabletask ensure_response_format: set _response_format before accessing .value

* Fix ollama .value and ai_model_id issues, handle None in content list

- Fix ollama _chat_client: remove .value on string literals
- Fix ollama _chat_client: rename ai_model_id to model_id
- Fix _parse_content_list: skip None values gracefully

* Fix A2AAgent type signature to include Content

* Fix Role/FinishReason NewType dict annotations and improve test coverage to 95%

* Fix mypy errors for Role/FinishReason NewType usage

* Fix Role.TOOL and Role.ASSISTANT usage in _orchestrator_helpers.py

* Fix Role NewType usage in durabletask _models.py

python/samples/getting_started/agents/anthropic/anthropic_basic.py

@@ -4,8 +4,8 @@ import asyncio
 from random import randint
 from typing import Annotated
 
-from agent_framework.anthropic import AnthropicClient
 from agent_framework import tool
+from agent_framework.anthropic import AnthropicClient
 
 """
 Anthropic Chat Agent Example
@@ -13,6 +13,7 @@ Anthropic Chat Agent Example
 This sample demonstrates using Anthropic with an agent and a single custom tool.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_ai/azure_ai_basic.py

@@ -4,10 +4,10 @@ import asyncio
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureAIProjectAgentProvider
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure AI Agent Basic Example
@@ -16,6 +16,7 @@ This sample demonstrates basic usage of AzureAIProjectAgentProvider.
 Shows both streaming and non-streaming responses with function tools.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_ai/azure_ai_provider_methods.py

@@ -5,12 +5,12 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureAIProjectAgentProvider
 from azure.ai.projects.aio import AIProjectClient
 from azure.ai.projects.models import AgentReference, PromptAgentDefinition
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure AI Project Agent Provider Methods Example
@@ -26,6 +26,7 @@ with different configurations, which is efficient for multi-agent scenarios.
 Each method returns a ChatAgent that can be used for conversations.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_ai/azure_ai_use_latest_version.py

@@ -4,10 +4,10 @@ import asyncio
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureAIProjectAgentProvider
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure AI Agent Latest Version Example
@@ -17,6 +17,7 @@ instead of creating a new agent version on each instantiation. The first call cr
 while subsequent calls with `get_agent()` reuse the latest agent version.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_ai/azure_ai_with_code_interpreter_file_generation.py

@@ -5,7 +5,6 @@ import asyncio
 from agent_framework import (
     AgentResponseUpdate,
     HostedCodeInterpreterTool,
-    tool,
 )
 from agent_framework.azure import AzureAIProjectAgentProvider
 from azure.identity.aio import AzureCliCredential

python/samples/getting_started/agents/azure_ai/azure_ai_with_existing_conversation.py

@@ -4,11 +4,11 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureAIProjectAgentProvider
 from azure.ai.projects.aio import AIProjectClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure AI Agent Existing Conversation Example
@@ -16,6 +16,7 @@ Azure AI Agent Existing Conversation Example
 This sample demonstrates usage of AzureAIProjectAgentProvider with existing conversation created on service side.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py

@@ -5,10 +5,10 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureAIProjectAgentProvider
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure AI Agent with Explicit Settings Example
@@ -17,6 +17,7 @@ This sample demonstrates creating Azure AI Agents with explicit configuration
 settings rather than relying on environment variable defaults.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_ai/azure_ai_with_hosted_mcp.py

@@ -25,10 +25,10 @@ async def handle_approvals_without_thread(query: str, agent: "AgentProtocol") ->
                 f"User Input Request for function from {agent.name}: {user_input_needed.function_call.name}"
                 f" with arguments: {user_input_needed.function_call.arguments}"
             )
-            new_inputs.append(ChatMessage(role="assistant", contents=[user_input_needed]))
+            new_inputs.append(ChatMessage("assistant", [user_input_needed]))
             user_approval = input("Approve function call? (y/n): ")
             new_inputs.append(
-                ChatMessage(role="user", contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
+                ChatMessage("user", [user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
             )
 
         result = await agent.run(new_inputs, store=False)

python/samples/getting_started/agents/azure_ai/azure_ai_with_response_format.py

@@ -41,12 +41,13 @@ async def main() -> None:
         print(f"User: {query}")
         result = await agent.run(query)
 
-        if release_brief := result.try_parse_value(ReleaseBrief):
+        try:
+            release_brief = result.value
             print("Agent:")
             print(f"Feature: {release_brief.feature}")
             print(f"Benefit: {release_brief.benefit}")
             print(f"Launch date: {release_brief.launch_date}")
-        else:
+        except Exception:
             print(f"Failed to parse response: {result.text}")
 
 

python/samples/getting_started/agents/azure_ai_agent/azure_ai_basic.py

@@ -4,10 +4,10 @@ import asyncio
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureAIAgentsProvider
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure AI Agent Basic Example
@@ -16,6 +16,7 @@ This sample demonstrates basic usage of AzureAIAgentsProvider to create agents w
 lifecycle management. Shows both streaming and non-streaming responses with function tools.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_ai_agent/azure_ai_provider_methods.py

@@ -5,11 +5,11 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureAIAgentsProvider
 from azure.ai.agents.aio import AgentsClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure AI Agent Provider Methods Example
@@ -20,6 +20,7 @@ This sample demonstrates the methods available on the AzureAIAgentsProvider clas
 - as_agent(): Wrap an SDK Agent object without making HTTP calls
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter_file_generation.py

@@ -7,7 +7,6 @@ from agent_framework import (
     AgentResponseUpdate,
     HostedCodeInterpreterTool,
     HostedFileContent,
-    tool,
 )
 from agent_framework.azure import AzureAIAgentsProvider
 from azure.ai.agents.aio import AgentsClient

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_existing_thread.py

@@ -5,11 +5,11 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureAIAgentsProvider
 from azure.ai.agents.aio import AgentsClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure AI Agent with Existing Thread Example
@@ -18,6 +18,7 @@ This sample demonstrates working with pre-existing conversation threads
 by providing thread IDs for thread reuse patterns.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_explicit_settings.py

@@ -5,10 +5,10 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureAIAgentsProvider
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure AI Agent with Explicit Settings Example
@@ -17,6 +17,7 @@ This sample demonstrates creating Azure AI Agents with explicit configuration
 settings rather than relying on environment variable defaults.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_function_tools.py

@@ -5,10 +5,10 @@ from datetime import datetime, timezone
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureAIAgentsProvider
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure AI Agent with Function Tools Example
@@ -17,6 +17,7 @@ This sample demonstrates function tool integration with Azure AI Agents,
 showing both agent-level and query-level tool configuration patterns.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(
@@ -26,6 +27,7 @@ def get_weather(
     conditions = ["sunny", "cloudy", "rainy", "stormy"]
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
 
+
 @tool(approval_mode="never_require")
 def get_time() -> str:
     """Get the current UTC time."""

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_multiple_tools.py

@@ -34,9 +34,9 @@ To set up Bing Grounding:
 4. Copy the connection ID and set it as the BING_CONNECTION_ID environment variable
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
-
 def get_time() -> str:
     """Get the current UTC time."""
     current_time = datetime.now(timezone.utc)

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_response_format.py

@@ -56,13 +56,14 @@ async def main() -> None:
 
         result1 = await agent.run(query1)
 
-        if weather := result1.try_parse_value(WeatherInfo):
+        try:
+            weather = result1.value
             print("Agent:")
             print(f"  Location: {weather.location}")
             print(f"  Temperature: {weather.temperature}")
             print(f"  Conditions: {weather.conditions}")
             print(f"  Recommendation: {weather.recommendation}")
-        else:
+        except Exception:
             print(f"Failed to parse response: {result1.text}")
 
         # Request 2: Override response_format at runtime with CityInfo
@@ -72,12 +73,13 @@ async def main() -> None:
 
         result2 = await agent.run(query2, options={"response_format": CityInfo})
 
-        if city := result2.try_parse_value(CityInfo):
+        try:
+            city = result2.value
             print("Agent:")
             print(f"  City: {city.city_name}")
             print(f"  Population: {city.population}")
             print(f"  Country: {city.country}")
-        else:
+        except Exception:
             print(f"Failed to parse response: {result2.text}")
 
 

python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_thread.py

@@ -4,8 +4,7 @@ import asyncio
 from random import randint
 from typing import Annotated
 
-from agent_framework import AgentThread
-from agent_framework import tool
+from agent_framework import AgentThread, tool
 from agent_framework.azure import AzureAIAgentsProvider
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
@@ -17,6 +16,7 @@ This sample demonstrates thread management with Azure AI Agents, comparing
 automatic thread creation with explicit thread management for persistent context.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_openai/azure_assistants_basic.py

@@ -4,10 +4,10 @@ import asyncio
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureOpenAIAssistantsClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure OpenAI Assistants Basic Example
@@ -16,6 +16,7 @@ This sample demonstrates basic usage of AzureOpenAIAssistantsClient with automat
 assistant lifecycle management, showing both streaming and non-streaming responses.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_openai/azure_assistants_with_existing_assistant.py

@@ -5,8 +5,7 @@ import os
 from random import randint
 from typing import Annotated
 
-from agent_framework import ChatAgent
-from agent_framework import tool
+from agent_framework import ChatAgent, tool
 from agent_framework.azure import AzureOpenAIAssistantsClient
 from azure.identity import AzureCliCredential, get_bearer_token_provider
 from openai import AsyncAzureOpenAI
@@ -19,6 +18,7 @@ This sample demonstrates working with pre-existing Azure OpenAI Assistants
 using existing assistant IDs rather than creating new ones.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_openai/azure_assistants_with_explicit_settings.py

@@ -5,10 +5,10 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureOpenAIAssistantsClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure OpenAI Assistants with Explicit Settings Example
@@ -17,6 +17,7 @@ This sample demonstrates creating Azure OpenAI Assistants with explicit configur
 settings rather than relying on environment variable defaults.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_openai/azure_assistants_with_function_tools.py

@@ -5,8 +5,7 @@ from datetime import datetime, timezone
 from random import randint
 from typing import Annotated
 
-from agent_framework import ChatAgent
-from agent_framework import tool
+from agent_framework import ChatAgent, tool
 from agent_framework.azure import AzureOpenAIAssistantsClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
@@ -18,6 +17,7 @@ This sample demonstrates function tool integration with Azure OpenAI Assistants,
 showing both agent-level and query-level tool configuration patterns.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(
@@ -27,6 +27,7 @@ def get_weather(
     conditions = ["sunny", "cloudy", "rainy", "stormy"]
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
 
+
 @tool(approval_mode="never_require")
 def get_time() -> str:
     """Get the current UTC time."""

python/samples/getting_started/agents/azure_openai/azure_assistants_with_thread.py

@@ -4,8 +4,7 @@ import asyncio
 from random import randint
 from typing import Annotated
 
-from agent_framework import AgentThread, ChatAgent
-from agent_framework import tool
+from agent_framework import AgentThread, ChatAgent, tool
 from agent_framework.azure import AzureOpenAIAssistantsClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
@@ -17,6 +16,7 @@ This sample demonstrates thread management with Azure OpenAI Assistants, compari
 automatic thread creation with explicit thread management for persistent context.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_openai/azure_chat_client_basic.py

@@ -4,10 +4,10 @@ import asyncio
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure OpenAI Chat Client Basic Example
@@ -16,6 +16,7 @@ This sample demonstrates basic usage of AzureOpenAIChatClient for direct chat-ba
 interactions, showing both streaming and non-streaming responses.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_openai/azure_chat_client_with_explicit_settings.py

@@ -5,10 +5,10 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure OpenAI Chat Client with Explicit Settings Example
@@ -17,6 +17,7 @@ This sample demonstrates creating Azure OpenAI Chat Client with explicit configu
 settings rather than relying on environment variable defaults.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_openai/azure_chat_client_with_function_tools.py

@@ -5,8 +5,7 @@ from datetime import datetime, timezone
 from random import randint
 from typing import Annotated
 
-from agent_framework import ChatAgent
-from agent_framework import tool
+from agent_framework import ChatAgent, tool
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
@@ -18,6 +17,7 @@ This sample demonstrates function tool integration with Azure OpenAI Chat Client
 showing both agent-level and query-level tool configuration patterns.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(
@@ -27,6 +27,7 @@ def get_weather(
     conditions = ["sunny", "cloudy", "rainy", "stormy"]
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
 
+
 @tool(approval_mode="never_require")
 def get_time() -> str:
     """Get the current UTC time."""

python/samples/getting_started/agents/azure_openai/azure_chat_client_with_thread.py

@@ -4,8 +4,7 @@ import asyncio
 from random import randint
 from typing import Annotated
 
-from agent_framework import AgentThread, ChatAgent, ChatMessageStore
-from agent_framework import tool
+from agent_framework import AgentThread, ChatAgent, ChatMessageStore, tool
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
@@ -17,6 +16,7 @@ This sample demonstrates thread management with Azure OpenAI Chat Client, compar
 automatic thread creation with explicit thread management for persistent context.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_openai/azure_responses_client_basic.py

@@ -4,10 +4,10 @@ import asyncio
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureOpenAIResponsesClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure OpenAI Responses Client Basic Example
@@ -16,6 +16,7 @@ This sample demonstrates basic usage of AzureOpenAIResponsesClient for structure
 response generation, showing both streaming and non-streaming responses.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_explicit_settings.py

@@ -5,10 +5,10 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.azure import AzureOpenAIResponsesClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
-from agent_framework import tool
 
 """
 Azure OpenAI Responses Client with Explicit Settings Example
@@ -17,6 +17,7 @@ This sample demonstrates creating Azure OpenAI Responses Client with explicit co
 settings rather than relying on environment variable defaults.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_function_tools.py

@@ -5,8 +5,7 @@ from datetime import datetime, timezone
 from random import randint
 from typing import Annotated
 
-from agent_framework import ChatAgent
-from agent_framework import tool
+from agent_framework import ChatAgent, tool
 from agent_framework.azure import AzureOpenAIResponsesClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
@@ -18,6 +17,7 @@ This sample demonstrates function tool integration with Azure OpenAI Responses C
 showing both agent-level and query-level tool configuration patterns.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(
@@ -27,6 +27,7 @@ def get_weather(
     conditions = ["sunny", "cloudy", "rainy", "stormy"]
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
 
+
 @tool(approval_mode="never_require")
 def get_time() -> str:
     """Get the current UTC time."""

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_hosted_mcp.py

@@ -30,10 +30,10 @@ async def handle_approvals_without_thread(query: str, agent: "AgentProtocol"):
                 f"User Input Request for function from {agent.name}: {user_input_needed.function_call.name}"
                 f" with arguments: {user_input_needed.function_call.arguments}"
             )
-            new_inputs.append(ChatMessage(role="assistant", contents=[user_input_needed]))
+            new_inputs.append(ChatMessage("assistant", [user_input_needed]))
             user_approval = input("Approve function call? (y/n): ")
             new_inputs.append(
-                ChatMessage(role="user", contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
+                ChatMessage("user", [user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
             )
 
         result = await agent.run(new_inputs)
@@ -71,7 +71,7 @@ async def handle_approvals_with_thread_streaming(query: str, agent: "AgentProtoc
     new_input_added = True
     while new_input_added:
         new_input_added = False
-        new_input.append(ChatMessage(role="user", text=query))
+        new_input.append(ChatMessage("user", [query]))
         async for update in agent.run_stream(new_input, thread=thread, store=True):
             if update.user_input_requests:
                 for user_input_needed in update.user_input_requests:

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_thread.py

@@ -4,8 +4,7 @@ import asyncio
 from random import randint
 from typing import Annotated
 
-from agent_framework import AgentThread, ChatAgent
-from agent_framework import tool
+from agent_framework import AgentThread, ChatAgent, tool
 from agent_framework.azure import AzureOpenAIResponsesClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
@@ -17,6 +16,7 @@ This sample demonstrates thread management with Azure OpenAI Responses Client, c
 automatic thread creation with explicit thread management for persistent context.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

python/samples/getting_started/agents/custom/custom_agent.py

@@ -11,8 +11,6 @@ from agent_framework import (
     BaseAgent,
     ChatMessage,
     Content,
-    Role,
-    tool,
 )
 
 """
@@ -77,8 +75,8 @@ class EchoAgent(BaseAgent):
 
         if not normalized_messages:
             response_message = ChatMessage(
-                role=Role.ASSISTANT,
-                contents=[Content.from_text(text="Hello! I'm a custom echo agent. Send me a message and I'll echo it back.")],
+                "assistant",
+                [Content.from_text(text="Hello! I'm a custom echo agent. Send me a message and I'll echo it back.")],
             )
         else:
             # For simplicity, echo the last user message
@@ -88,7 +86,7 @@ class EchoAgent(BaseAgent):
             else:
                 echo_text = f"{self.echo_prefix}[Non-text message received]"
 
-            response_message = ChatMessage(role=Role.ASSISTANT, contents=[Content.from_text(text=echo_text)])
+            response_message = ChatMessage("assistant", [Content.from_text(text=echo_text)])
 
         # Notify the thread of new messages if provided
         if thread is not None:
@@ -134,7 +132,7 @@ class EchoAgent(BaseAgent):
 
             yield AgentResponseUpdate(
                 contents=[Content.from_text(text=chunk_text)],
-                role=Role.ASSISTANT,
+                role="assistant",
             )
 
             # Small delay to simulate streaming
@@ -142,7 +140,7 @@ class EchoAgent(BaseAgent):
 
         # Notify the thread of the complete response if provided
         if thread is not None:
-            complete_response = ChatMessage(role=Role.ASSISTANT, contents=[Content.from_text(text=response_text)])
+            complete_response = ChatMessage("assistant", [Content.from_text(text=response_text)])
             await self._notify_thread_of_new_messages(thread, normalized_messages, complete_response)
 
 

python/samples/getting_started/agents/custom/custom_chat_client.py

@@ -12,10 +12,8 @@ from agent_framework import (
     ChatResponse,
     ChatResponseUpdate,
     Content,
-    Role,
     use_chat_middleware,
     use_function_invocation,
-    tool,
 )
 from agent_framework._clients import TOptions_co
 
@@ -68,7 +66,7 @@ class EchoingChatClient(BaseChatClient[TOptions_co], Generic[TOptions_co]):
             # Echo the last user message
             last_user_message = None
             for message in reversed(messages):
-                if message.role == Role.USER:
+                if message.role == "user":
                     last_user_message = message
                     break
 
@@ -77,7 +75,7 @@ class EchoingChatClient(BaseChatClient[TOptions_co], Generic[TOptions_co]):
             else:
                 response_text = f"{self.prefix} [No text message found]"
 
-        response_message = ChatMessage(role=Role.ASSISTANT, contents=[Content.from_text(text=response_text)])
+        response_message = ChatMessage("assistant", [Content.from_text(text=response_text)])
 
         return ChatResponse(
             messages=[response_message],
@@ -104,7 +102,7 @@ class EchoingChatClient(BaseChatClient[TOptions_co], Generic[TOptions_co]):
             for char in response_text:
                 yield ChatResponseUpdate(
                     contents=[Content.from_text(text=char)],
-                    role=Role.ASSISTANT,
+                    role="assistant",
                     response_id=f"echo-stream-resp-{random.randint(1000, 9999)}",
                     model_id="echo-model-v1",
                 )

python/samples/getting_started/agents/ollama/ollama_agent_basic.py

@@ -3,8 +3,8 @@
 import asyncio
 from datetime import datetime
 
-from agent_framework.ollama import OllamaChatClient
 from agent_framework import tool
+from agent_framework.ollama import OllamaChatClient
 
 """
 Ollama Agent Basic Example
@@ -18,6 +18,7 @@ https://ollama.com/
 
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_time(location: str) -> str:

python/samples/getting_started/agents/ollama/ollama_chat_client.py

@@ -3,8 +3,8 @@
 import asyncio
 from datetime import datetime
 
-from agent_framework.ollama import OllamaChatClient
 from agent_framework import tool
+from agent_framework.ollama import OllamaChatClient
 
 """
 Ollama Chat Client Example
@@ -18,6 +18,7 @@ https://ollama.com/
 
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_time():

python/samples/getting_started/agents/ollama/ollama_chat_multimodal.py

@@ -2,7 +2,7 @@
 
 import asyncio
 
-from agent_framework import ChatMessage, Content, Role
+from agent_framework import ChatMessage, Content
 from agent_framework.ollama import OllamaChatClient
 
 """
@@ -33,7 +33,7 @@ async def test_image() -> None:
     image_uri = create_sample_image()
 
     message = ChatMessage(
-        role=Role.USER,
+        role="user",
         contents=[
             Content.from_text(text="What's in this image?"),
             Content.from_uri(uri=image_uri, media_type="image/png"),

python/samples/getting_started/agents/ollama/ollama_with_openai_chat_client.py

@@ -5,8 +5,8 @@ import os
 from random import randint
 from typing import Annotated
 
-from agent_framework.openai import OpenAIChatClient
 from agent_framework import tool
+from agent_framework.openai import OpenAIChatClient
 
 """
 Ollama with OpenAI Chat Client Example
@@ -20,6 +20,7 @@ Environment Variables:
 - OLLAMA_MODEL: The model name to use (e.g., "mistral", "llama3.2", "phi3")
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

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

@@ -5,10 +5,10 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.openai import OpenAIAssistantProvider
 from openai import AsyncOpenAI
 from pydantic import Field
-from agent_framework import tool
 
 """
 OpenAI Assistants Basic Example
@@ -17,6 +17,7 @@ This sample demonstrates basic usage of OpenAIAssistantProvider with automatic
 assistant lifecycle management, showing both streaming and non-streaming responses.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

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

@@ -5,10 +5,10 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.openai import OpenAIAssistantProvider
 from openai import AsyncOpenAI
 from pydantic import Field
-from agent_framework import tool
 
 """
 OpenAI Assistant Provider Methods Example
@@ -19,6 +19,7 @@ This sample demonstrates the methods available on the OpenAIAssistantProvider cl
 - as_agent(): Wrap an SDK Assistant object without making HTTP calls
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

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

@@ -5,10 +5,10 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.openai import OpenAIAssistantProvider
 from openai import AsyncOpenAI
 from pydantic import Field
-from agent_framework import tool
 
 """
 OpenAI Assistants with Existing Assistant Example
@@ -17,6 +17,7 @@ This sample demonstrates working with pre-existing OpenAI Assistants
 using the provider's get_agent() and as_agent() methods.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

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

@@ -5,10 +5,10 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.openai import OpenAIAssistantProvider
 from openai import AsyncOpenAI
 from pydantic import Field
-from agent_framework import tool
 
 """
 OpenAI Assistants with Explicit Settings Example
@@ -17,6 +17,7 @@ This sample demonstrates creating OpenAI Assistants with explicit configuration
 settings rather than relying on environment variable defaults.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

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

@@ -6,10 +6,10 @@ from datetime import datetime, timezone
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.openai import OpenAIAssistantProvider
 from openai import AsyncOpenAI
 from pydantic import Field
-from agent_framework import tool
 
 """
 OpenAI Assistants with Function Tools Example
@@ -18,6 +18,7 @@ This sample demonstrates function tool integration with OpenAI Assistants,
 showing both agent-level and query-level tool configuration patterns.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(
@@ -27,6 +28,7 @@ def get_weather(
     conditions = ["sunny", "cloudy", "rainy", "stormy"]
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}C."
 
+
 @tool(approval_mode="never_require")
 def get_time() -> str:
     """Get the current UTC time."""

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

@@ -59,13 +59,14 @@ async def main() -> None:
 
             result1 = await agent.run(query1)
 
-            if weather := result1.try_parse_value(WeatherInfo):
+            try:
+                weather = result1.value
                 print("Agent:")
                 print(f"  Location: {weather.location}")
                 print(f"  Temperature: {weather.temperature}")
                 print(f"  Conditions: {weather.conditions}")
                 print(f"  Recommendation: {weather.recommendation}")
-            else:
+            except Exception:
                 print(f"Failed to parse response: {result1.text}")
 
             # Request 2: Override response_format at runtime with CityInfo
@@ -75,12 +76,13 @@ async def main() -> None:
 
             result2 = await agent.run(query2, options={"response_format": CityInfo})
 
-            if city := result2.try_parse_value(CityInfo):
+            try:
+                city = result2.value
                 print("Agent:")
                 print(f"  City: {city.city_name}")
                 print(f"  Population: {city.population}")
                 print(f"  Country: {city.country}")
-            else:
+            except Exception:
                 print(f"Failed to parse response: {result2.text}")
         finally:
             await client.beta.assistants.delete(agent.id)

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

@@ -5,8 +5,7 @@ import os
 from random import randint
 from typing import Annotated
 
-from agent_framework import AgentThread
-from agent_framework import tool
+from agent_framework import AgentThread, tool
 from agent_framework.openai import OpenAIAssistantProvider
 from openai import AsyncOpenAI
 from pydantic import Field
@@ -18,6 +17,7 @@ This sample demonstrates thread management with OpenAI Assistants, showing
 persistent conversation threads and context preservation across interactions.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

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

@@ -4,8 +4,8 @@ import asyncio
 from random import randint
 from typing import Annotated
 
-from agent_framework.openai import OpenAIChatClient
 from agent_framework import tool
+from agent_framework.openai import OpenAIChatClient
 
 """
 OpenAI Chat Client Basic Example
@@ -14,6 +14,7 @@ This sample demonstrates basic usage of OpenAIChatClient for direct chat-based
 interactions, showing both streaming and non-streaming responses.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

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

@@ -5,9 +5,9 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.openai import OpenAIChatClient
 from pydantic import Field
-from agent_framework import tool
 
 """
 OpenAI Chat Client with Explicit Settings Example
@@ -16,6 +16,7 @@ This sample demonstrates creating OpenAI Chat Client with explicit configuration
 settings rather than relying on environment variable defaults.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

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

@@ -5,8 +5,7 @@ from datetime import datetime, timezone
 from random import randint
 from typing import Annotated
 
-from agent_framework import ChatAgent
-from agent_framework import tool
+from agent_framework import ChatAgent, tool
 from agent_framework.openai import OpenAIChatClient
 from pydantic import Field
 
@@ -17,6 +16,7 @@ This sample demonstrates function tool integration with OpenAI Chat Client,
 showing both agent-level and query-level tool configuration patterns.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(
@@ -26,6 +26,7 @@ def get_weather(
     conditions = ["sunny", "cloudy", "rainy", "stormy"]
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
 
+
 @tool(approval_mode="never_require")
 def get_time() -> str:
     """Get the current UTC time."""

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

@@ -4,8 +4,7 @@ import asyncio
 from random import randint
 from typing import Annotated
 
-from agent_framework import AgentThread, ChatAgent, ChatMessageStore
-from agent_framework import tool
+from agent_framework import AgentThread, ChatAgent, ChatMessageStore, tool
 from agent_framework.openai import OpenAIChatClient
 from pydantic import Field
 
@@ -16,6 +15,7 @@ This sample demonstrates thread management with OpenAI Chat Client, showing
 conversation threads and message history preservation across interactions.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

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

@@ -4,8 +4,7 @@ import asyncio
 from random import randint
 from typing import Annotated
 
-from agent_framework import ChatAgent
-from agent_framework import tool
+from agent_framework import ChatAgent, tool
 from agent_framework.openai import OpenAIResponsesClient
 from pydantic import Field
 
@@ -16,6 +15,7 @@ This sample demonstrates basic usage of OpenAIResponsesClient for structured
 response generation, showing both streaming and non-streaming responses.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

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

@@ -8,7 +8,6 @@ from agent_framework import (
     CodeInterpreterToolResultContent,
     Content,
     HostedCodeInterpreterTool,
-    tool,
 )
 from agent_framework.openai import OpenAIResponsesClient
 

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

@@ -5,9 +5,9 @@ import os
 from random import randint
 from typing import Annotated
 
+from agent_framework import tool
 from agent_framework.openai import OpenAIResponsesClient
 from pydantic import Field
-from agent_framework import tool
 
 """
 OpenAI Responses Client with Explicit Settings Example
@@ -16,6 +16,7 @@ This sample demonstrates creating OpenAI Responses Client with explicit configur
 settings rather than relying on environment variable defaults.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(

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

@@ -5,8 +5,7 @@ from datetime import datetime, timezone
 from random import randint
 from typing import Annotated
 
-from agent_framework import ChatAgent
-from agent_framework import tool
+from agent_framework import ChatAgent, tool
 from agent_framework.openai import OpenAIResponsesClient
 from pydantic import Field
 
@@ -17,6 +16,7 @@ This sample demonstrates function tool integration with OpenAI Responses Client,
 showing both agent-level and query-level tool configuration patterns.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(
@@ -26,6 +26,7 @@ def get_weather(
     conditions = ["sunny", "cloudy", "rainy", "stormy"]
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
 
+
 @tool(approval_mode="never_require")
 def get_time() -> str:
     """Get the current UTC time."""

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

@@ -29,10 +29,10 @@ async def handle_approvals_without_thread(query: str, agent: "AgentProtocol"):
                 f"User Input Request for function from {agent.name}: {user_input_needed.function_call.name}"
                 f" with arguments: {user_input_needed.function_call.arguments}"
             )
-            new_inputs.append(ChatMessage(role="assistant", contents=[user_input_needed]))
+            new_inputs.append(ChatMessage("assistant", [user_input_needed]))
             user_approval = input("Approve function call? (y/n): ")
             new_inputs.append(
-                ChatMessage(role="user", contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
+                ChatMessage("user", [user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
             )
 
         result = await agent.run(new_inputs)
@@ -70,7 +70,7 @@ async def handle_approvals_with_thread_streaming(query: str, agent: "AgentProtoc
     new_input_added = True
     while new_input_added:
         new_input_added = False
-        new_input.append(ChatMessage(role="user", text=query))
+        new_input.append(ChatMessage("user", [query]))
         async for update in agent.run_stream(new_input, thread=thread, store=True):
             if update.user_input_requests:
                 for user_input_needed in update.user_input_requests:

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

@@ -4,8 +4,7 @@ import asyncio
 from random import randint
 from typing import Annotated
 
-from agent_framework import AgentThread, ChatAgent
-from agent_framework import tool
+from agent_framework import AgentThread, ChatAgent, tool
 from agent_framework.openai import OpenAIResponsesClient
 from pydantic import Field
 
@@ -16,6 +15,7 @@ This sample demonstrates thread management with OpenAI Responses Client, showing
 persistent conversation context and simplified response handling.
 """
 
+
 # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_weather(