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
2026-06-16 21:04:09 +08:00 · 2026-02-04 11:13:23 +01:00
parent ef798629e5
commit 838a7fd61d
341 changed files with 3766 additions and 3228 deletions
@@ -11,12 +11,13 @@ Prerequisites: set `AZURE_OPENAI_ENDPOINT` and `AZURE_OPENAI_CHAT_DEPLOYMENT_NAM
 import logging
 from typing import Any

+from agent_framework import tool
 from agent_framework.azure import AgentFunctionApp, AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
-from agent_framework import tool

 logger = logging.getLogger(__name__)

+
 # 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(location: str) -> dict[str, Any]:
@@ -32,6 +33,7 @@ def get_weather(location: str) -> dict[str, Any]:
    logger.info(f"✓ [TOOL RESULT] {result}")
    return result

+
@tool(approval_mode="never_require")
 def calculate_tip(bill_amount: float, tip_percentage: float = 15.0) -> dict[str, Any]:
    """Calculate tip amount and total bill."""
@@ -8,9 +8,9 @@ as a message broker. It enables clients to disconnect and reconnect without losi

 import asyncio
 import time
+from collections.abc import AsyncIterator
 from dataclasses import dataclass
 from datetime import timedelta
-from collections.abc import AsyncIterator

 import redis.asyncio as aioredis

@@ -153,13 +153,12 @@ def _get_weather_recommendation(condition: str) -> str:

    if "rain" in condition_lower or "drizzle" in condition_lower:
        return "Bring an umbrella and waterproof jacket. Consider indoor activities for backup."
-    elif "fog" in condition_lower:
+    if "fog" in condition_lower:
        return "Morning visibility may be limited. Plan outdoor sightseeing for afternoon."
-    elif "cold" in condition_lower:
+    if "cold" in condition_lower:
        return "Layer up with warm clothing. Hot drinks and cozy cafés recommended."
-    elif "hot" in condition_lower or "warm" in condition_lower:
+    if "hot" in condition_lower or "warm" in condition_lower:
        return "Stay hydrated and use sunscreen. Plan strenuous activities for cooler morning hours."
-    elif "thunder" in condition_lower or "storm" in condition_lower:
+    if "thunder" in condition_lower or "storm" in condition_lower:
        return "Keep an eye on weather updates. Have indoor alternatives ready."
-    else:
-        return "Pleasant conditions expected. Great day for outdoor exploration!"
+    return "Pleasant conditions expected. Great day for outdoor exploration!"
@@ -102,9 +102,10 @@ def spam_detection_orchestration(context: DurableOrchestrationContext) -> Genera
        options={"response_format": SpamDetectionResult},
    )

-    spam_result = spam_result_raw.try_parse_value(SpamDetectionResult)
-    if spam_result is None:
-        raise ValueError("Failed to parse spam detection result")
+    try:
+        spam_result = spam_result_raw.value
+    except Exception as ex:
+        raise ValueError("Failed to parse spam detection result") from ex

    if spam_result.is_spam:
        result = yield context.call_activity("handle_spam_email", spam_result.reason)  # type: ignore[misc]
@@ -125,9 +126,10 @@ def spam_detection_orchestration(context: DurableOrchestrationContext) -> Genera
        options={"response_format": EmailResponse},
    )

-    email_result = email_result_raw.try_parse_value(EmailResponse)
-    if email_result is None:
-        raise ValueError("Failed to parse email response")
+    try:
+        email_result = email_result_raw.value
+    except Exception as ex:
+        raise ValueError("Failed to parse email response") from ex

    result = yield context.call_activity("send_email", email_result.response)  # type: ignore[misc]
    return result
@@ -137,11 +137,11 @@ def content_generation_hitl_orchestration(context: DurableOrchestrationContext)
            context.set_custom_status(
                "Content rejected by human reviewer. Incorporating feedback and regenerating..."
            )
-            
+
            # Check if we've exhausted attempts
            if attempt >= payload.max_review_attempts:
                break
-            
+
            rewrite_prompt = (
                "The content was rejected by a human reviewer. Please rewrite the article incorporating their feedback.\n\n"
                f"Human Feedback: {approval_payload.feedback or 'No feedback provided.'}"
@@ -152,9 +152,10 @@ def content_generation_hitl_orchestration(context: DurableOrchestrationContext)
                options={"response_format": GeneratedContent},
            )

-            content = rewritten_raw.try_parse_value(GeneratedContent)
-            if content is None:
-                raise ValueError("Agent returned no content after rewrite.")
+            try:
+                content = rewritten_raw.value
+            except Exception as ex:
+                raise ValueError("Agent returned no content after rewrite.") from ex
        else:
            context.set_custom_status(
                f"Human approval timed out after {payload.approval_timeout_hours} hour(s). Treating as rejection."
@@ -162,7 +163,7 @@ def content_generation_hitl_orchestration(context: DurableOrchestrationContext)
            raise TimeoutError(
                f"Human approval timed out after {payload.approval_timeout_hours} hour(s)."
            )
-    
+
    # If we exit the loop without returning, max attempts were exhausted
    context.set_custom_status("Max review attempts exhausted.")
    raise RuntimeError(