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/durabletask/02_multi_agent/client.py

@@ -41,12 +41,12 @@ def get_client(
     """
     taskhub_name = taskhub or os.getenv("TASKHUB", "default")
     endpoint_url = endpoint or os.getenv("ENDPOINT", "http://localhost:8080")
-    
+
     logger.debug(f"Using taskhub: {taskhub_name}")
     logger.debug(f"Using endpoint: {endpoint_url}")
-    
+
     credential = None if endpoint_url == "http://localhost:8080" else DefaultAzureCredential()
-    
+
     dts_client = DurableTaskSchedulerClient(
         host_address=endpoint_url,
         secure_channel=endpoint_url != "http://localhost:8080",
@@ -54,7 +54,7 @@ def get_client(
         token_credential=credential,
         log_handler=log_handler
     )
-    
+
     return DurableAIAgentClient(dts_client)
 
 
@@ -65,45 +65,45 @@ def run_client(agent_client: DurableAIAgentClient) -> None:
         agent_client: The DurableAIAgentClient instance
     """
     logger.debug("Testing WeatherAgent")
-    
+
     # Get reference to WeatherAgent
     weather_agent = agent_client.get_agent("WeatherAgent")
     weather_thread = weather_agent.get_new_thread()
-    
+
     logger.debug(f"Created weather conversation thread: {weather_thread.session_id}")
-    
+
     # Test WeatherAgent
     weather_message = "What is the weather in Seattle?"
     logger.info(f"User: {weather_message}")
-    
+
     weather_response = weather_agent.run(weather_message, thread=weather_thread)
     logger.info(f"WeatherAgent: {weather_response.text} \n")
-    
+
     logger.debug("Testing MathAgent")
-    
+
     # Get reference to MathAgent
     math_agent = agent_client.get_agent("MathAgent")
     math_thread = math_agent.get_new_thread()
-    
+
     logger.debug(f"Created math conversation thread: {math_thread.session_id}")
-    
+
     # Test MathAgent
     math_message = "Calculate a 20% tip on a $50 bill"
     logger.info(f"User: {math_message}")
-    
+
     math_response = math_agent.run(math_message, thread=math_thread)
     logger.info(f"MathAgent: {math_response.text} \n")
-    
+
     logger.debug("Both agents completed successfully!")
 
 
 async def main() -> None:
     """Main entry point for the client application."""
     logger.debug("Starting Durable Task Multi-Agent Client...")
-    
+
     # Create client using helper function
     agent_client = get_client()
-    
+
     try:
         run_client(agent_client)
     except Exception as e:

python/samples/getting_started/durabletask/02_multi_agent/sample.py

@@ -15,10 +15,9 @@ To run this sample:
 
 import logging
 
-from dotenv import load_dotenv
-
 # Import helper functions from worker and client modules
 from client import get_client, run_client
+from dotenv import load_dotenv
 from worker import get_worker, setup_worker
 
 # Configure logging
@@ -29,26 +28,26 @@ logger = logging.getLogger(__name__)
 def main():
     """Main entry point - runs both worker and client in single process."""
     logger.debug("Starting Durable Task Multi-Agent Sample (Combined Worker + Client)...")
-    
+
     silent_handler = logging.NullHandler()
     # Create and start the worker using helper function and context manager
     with get_worker(log_handler=silent_handler) as dts_worker:
         # Register agents using helper function
         setup_worker(dts_worker)
-        
+
         # Start the worker
         dts_worker.start()
         logger.debug("Worker started and listening for requests...")
-        
+
         # Create the client using helper function
         agent_client = get_client(log_handler=silent_handler)
-        
+
         try:
             # Run client interactions using helper function
             run_client(agent_client)
         except Exception as e:
             logger.exception(f"Error during agent interaction: {e}")
-        
+
         logger.debug("Sample completed. Worker shutting down...")
 
 

python/samples/getting_started/durabletask/02_multi_agent/worker.py

@@ -101,12 +101,12 @@ def get_worker(
     """
     taskhub_name = taskhub or os.getenv("TASKHUB", "default")
     endpoint_url = endpoint or os.getenv("ENDPOINT", "http://localhost:8080")
-    
+
     logger.debug(f"Using taskhub: {taskhub_name}")
     logger.debug(f"Using endpoint: {endpoint_url}")
-    
+
     credential = None if endpoint_url == "http://localhost:8080" else DefaultAzureCredential()
-    
+
     return DurableTaskSchedulerWorker(
         host_address=endpoint_url,
         secure_channel=endpoint_url != "http://localhost:8080",
@@ -127,43 +127,43 @@ def setup_worker(worker: DurableTaskSchedulerWorker) -> DurableAIAgentWorker:
     """
     # Wrap it with the agent worker
     agent_worker = DurableAIAgentWorker(worker)
-    
+
     # Create and register both agents
     logger.debug("Creating and registering agents...")
     weather_agent = create_weather_agent()
     math_agent = create_math_agent()
-    
+
     agent_worker.add_agent(weather_agent)
     agent_worker.add_agent(math_agent)
-    
+
     logger.debug(f"✓ Registered agents: {weather_agent.name}, {math_agent.name}")
-    
+
     return agent_worker
 
 
 async def main():
     """Main entry point for the worker process."""
     logger.debug("Starting Durable Task Multi-Agent Worker...")
-    
+
     # Create a worker using the helper function
     worker = get_worker()
-    
+
     # Setup worker with agents
     setup_worker(worker)
-    
+
     logger.info("Worker is ready and listening for requests...")
     logger.info("Press Ctrl+C to stop. \n")
-    
+
     try:
         # Start the worker (this blocks until stopped)
         worker.start()
-        
+
         # Keep the worker running
         while True:
             await asyncio.sleep(1)
     except KeyboardInterrupt:
         logger.debug("Worker shutdown initiated")
-    
+
     logger.info("Worker stopped")