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
@@ -9,12 +9,10 @@ from agent_framework import (  # Core chat primitives used to build requests
    AgentExecutorResponse,
    ChatAgent,  # Output from an AgentExecutor
    ChatMessage,
-    Role,
    WorkflowBuilder,  # Fluent builder for wiring executors and edges
    WorkflowContext,  # Per-run context and event bus
    executor,  # Decorator to declare a Python function as a workflow executor
-    tool,
-)
+    )
 from agent_framework.azure import AzureOpenAIChatClient  # Thin client wrapper for Azure OpenAI chat models
 from azure.identity import AzureCliCredential  # Uses your az CLI login for credentials
 from pydantic import BaseModel  # Structured outputs for safer parsing
@@ -125,7 +123,7 @@ async def to_email_assistant_request(
    """
    # Bridge executor. Converts a structured DetectionResult into a ChatMessage and forwards it as a new request.
    detection = DetectionResult.model_validate_json(response.agent_response.text)
-    user_msg = ChatMessage(Role.USER, text=detection.email_content)
+    user_msg = ChatMessage("user", text=detection.email_content)
    await ctx.send_message(AgentExecutorRequest(messages=[user_msg], should_respond=True))


@@ -189,7 +187,7 @@ async def main() -> None:

    # Execute the workflow. Since the start is an AgentExecutor, pass an AgentExecutorRequest.
    # The workflow completes when it becomes idle (no more work to do).
-    request = AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=email)], should_respond=True)
+    request = AgentExecutorRequest(messages=[ChatMessage("user", text=email)], should_respond=True)
    events = await workflow.run(request)
    outputs = events.get_outputs()
    if outputs:
@@ -13,13 +13,11 @@ from agent_framework import (
    AgentExecutorResponse,
    ChatAgent,
    ChatMessage,
-    Role,
    WorkflowBuilder,
    WorkflowContext,
    WorkflowEvent,
    WorkflowOutputEvent,
    executor,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -93,7 +91,7 @@ async def store_email(email_text: str, ctx: WorkflowContext[AgentExecutorRequest
    await ctx.set_shared_state(CURRENT_EMAIL_ID_KEY, new_email.email_id)

    await ctx.send_message(
-        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=new_email.email_content)], should_respond=True)
+        AgentExecutorRequest(messages=[ChatMessage("user", text=new_email.email_content)], should_respond=True)
    )


@@ -120,7 +118,7 @@ async def submit_to_email_assistant(analysis: AnalysisResult, ctx: WorkflowConte

    email: Email = await ctx.get_shared_state(f"{EMAIL_STATE_PREFIX}{analysis.email_id}")
    await ctx.send_message(
-        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=email.email_content)], should_respond=True)
+        AgentExecutorRequest(messages=[ChatMessage("user", text=email.email_content)], should_respond=True)
    )


@@ -135,7 +133,7 @@ async def summarize_email(analysis: AnalysisResult, ctx: WorkflowContext[AgentEx
    # Only called for long NotSpam emails by selection_func
    email: Email = await ctx.get_shared_state(f"{EMAIL_STATE_PREFIX}{analysis.email_id}")
    await ctx.send_message(
-        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=email.email_content)], should_respond=True)
+        AgentExecutorRequest(messages=[ChatMessage("user", text=email.email_content)], should_respond=True)
    )


@@ -9,7 +9,6 @@ from agent_framework import (
    WorkflowContext,
    WorkflowOutputEvent,
    handler,
-    tool,
 )
 from typing_extensions import Never

@@ -10,11 +10,9 @@ from agent_framework import (
    ChatMessage,
    Executor,
    ExecutorCompletedEvent,
-    Role,
    WorkflowBuilder,
    WorkflowContext,
    handler,
-    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
@@ -97,7 +95,7 @@ class SubmitToJudgeAgent(Executor):
            f"Target: {self._target}\nGuess: {guess}\nResponse:"
        )
        await ctx.send_message(
-            AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=prompt)], should_respond=True),
+            AgentExecutorRequest(messages=[ChatMessage("user", text=prompt)], should_respond=True),
            target_id=self._judge_agent_id,
        )

@@ -13,12 +13,10 @@ from agent_framework import (  # Core chat primitives used to form LLM requests
    ChatAgent,  # Case entry for a switch-case edge group
    ChatMessage,
    Default,  # Default branch when no cases match
-    Role,
    WorkflowBuilder,  # Fluent builder for assembling the graph
    WorkflowContext,  # Per-run context and event bus
    executor,  # Decorator to turn a function into a workflow executor
-    tool,
-)
+    )
 from agent_framework.azure import AzureOpenAIChatClient  # Thin client for Azure OpenAI chat models
 from azure.identity import AzureCliCredential  # Uses your az CLI login for credentials
 from pydantic import BaseModel  # Structured outputs with validation
@@ -100,7 +98,7 @@ async def store_email(email_text: str, ctx: WorkflowContext[AgentExecutorRequest

    # Kick off the detector by forwarding the email as a user message to the spam_detection_agent.
    await ctx.send_message(
-        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=new_email.email_content)], should_respond=True)
+        AgentExecutorRequest(messages=[ChatMessage("user", text=new_email.email_content)], should_respond=True)
    )


@@ -121,7 +119,7 @@ async def submit_to_email_assistant(detection: DetectionResult, ctx: WorkflowCon
    # Load the original content from shared state using the id carried in DetectionResult.
    email: Email = await ctx.get_shared_state(f"{EMAIL_STATE_PREFIX}{detection.email_id}")
    await ctx.send_message(
-        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=email.email_content)], should_respond=True)
+        AgentExecutorRequest(messages=[ChatMessage("user", text=email.email_content)], should_respond=True)
    )