Python: [BREAKING] Simplify API: ChatAgent -> Agent, ChatMessage -> Message (#3747)

* [BREAKING] Rename ChatAgent -> Agent, ChatMessage -> Message, ChatClientProtocol -> SupportsChatGetResponse

Simplify the public API by removing redundant 'Chat' prefix from core types:
- ChatAgent -> Agent
- RawChatAgent -> RawAgent
- ChatMessage -> Message
- ChatClientProtocol -> SupportsChatGetResponse

Also renamed internal WorkflowMessage (was Message in _runner_context) to avoid collision.

No backward compatibility aliases - this is a clean breaking change.

* [BREAKING] Rename Agent chat_client parameter to client

* Fix rebase issues: WorkflowMessage references and broken markdown links

* Fix formatting and lint issues from code quality checks

* Fix import ordering in workflow sample files

* fixed rebase

* Fix test failures: use WorkflowMessage and A2AMessage after ChatMessage→Message rename

- Replace Message(data=..., source_id=...) with WorkflowMessage(...) in workflow tests
- Fix isinstance check in A2A agent to use A2AMessage instead of Message
- Fix import in test_workflow_observability.py (Message→WorkflowMessage)

* Fix lint, fmt, and sample errors after ChatMessage→Message rename

- Auto-fix 70+ ruff lint issues across samples (ChatMessage→Message refs)
- Fix HostedVectorStoreContent→Content.from_hosted_vector_store in file search sample
- Fix _normalize_messages→normalize_messages in custom agent sample
- Fix context.terminate→raise MiddlewareTermination in middleware samples
- Fix with_update_hook→with_transform_hook in override middleware sample
- Add TOptions_co import back to custom_chat_client sample
- Add noqa for FastAPI File() default in chatkit sample
- Fix B023 loop variable capture in weather agent sample

* fix: update Agent constructor calls from chat_client to client in declaration-only tool tests

* fix: add register_cleanup to devui lazy-loading proxy and type stub

* fixed tests and updated new pieces

* fix agui typevar

* fix merge errors

* fix merge conflicts

* fiux merge

* Remove unused links

---------

Co-authored-by: Evan Mattson <evan.mattson@microsoft.com>

python/packages/durabletask/agent_framework_durabletask/_durable_agent_state.py

@@ -37,8 +37,8 @@ from typing import Any, ClassVar, cast
 
 from agent_framework import (
     AgentResponse,
-    ChatMessage,
     Content,
+    Message,
     UsageDetails,
     get_logger,
 )
@@ -803,11 +803,11 @@ class DurableAgentStateMessage:
         )
 
     @staticmethod
-    def from_chat_message(chat_message: ChatMessage) -> DurableAgentStateMessage:
+    def from_chat_message(chat_message: Message) -> DurableAgentStateMessage:
         """Converts an Agent Framework chat message to a durable state message.
 
         Args:
-            chat_message: ChatMessage object with role, contents, and metadata to convert
+            chat_message: Message object with role, contents, and metadata to convert
 
         Returns:
             DurableAgentStateMessage with converted content items and metadata
@@ -824,15 +824,15 @@ class DurableAgentStateMessage:
         )
 
     def to_chat_message(self) -> Any:
-        """Converts this DurableAgentStateMessage back to an agent framework ChatMessage.
+        """Converts this DurableAgentStateMessage back to an agent framework Message.
 
         Returns:
-            ChatMessage object with role, contents, and metadata converted back to agent framework types
+            Message object with role, contents, and metadata converted back to agent framework types
         """
         # Convert DurableAgentStateContent objects back to agent_framework content objects
         ai_contents = [c.to_ai_content() for c in self.contents]
 
-        # Build kwargs for ChatMessage
+        # Build kwargs for Message
         kwargs: dict[str, Any] = {
             "role": self.role,
             "contents": ai_contents,
@@ -844,7 +844,7 @@ class DurableAgentStateMessage:
         if self.extension_data is not None:
             kwargs["additional_properties"] = self.extension_data
 
-        return ChatMessage(**kwargs)
+        return Message(**kwargs)
 
 
 class DurableAgentStateDataContent(DurableAgentStateContent):

python/packages/durabletask/agent_framework_durabletask/_entities.py

@@ -11,8 +11,8 @@ from typing import Any, cast
 from agent_framework import (
     AgentResponse,
     AgentResponseUpdate,
-    ChatMessage,
     Content,
+    Message,
     ResponseStream,
     SupportsAgentRun,
     get_logger,
@@ -150,7 +150,7 @@ class AgentEntity:
         self.state.data.conversation_history.append(state_request)
 
         try:
-            chat_messages: list[ChatMessage] = [
+            chat_messages: list[Message] = [
                 m.to_chat_message()
                 for entry in self.state.data.conversation_history
                 if not self._is_error_response(entry)
@@ -175,7 +175,7 @@ class AgentEntity:
         except Exception as exc:
             logger.exception("[AgentEntity.run] Agent execution failed.")
 
-            error_message = ChatMessage(
+            error_message = Message(
                 role="assistant", contents=[Content.from_error(message=str(exc), error_code=type(exc).__name__)]
             )
             error_response = AgentResponse(

python/packages/durabletask/agent_framework_durabletask/_executors.py

@@ -16,7 +16,7 @@ from abc import ABC, abstractmethod
 from datetime import datetime, timezone
 from typing import Any, Generic, TypeVar
 
-from agent_framework import AgentResponse, AgentThread, ChatMessage, Content, get_logger
+from agent_framework import AgentResponse, AgentThread, Content, Message, get_logger
 from durabletask.client import TaskHubGrpcClient
 from durabletask.entities import EntityInstanceId
 from durabletask.task import CompletableTask, CompositeTask, OrchestrationContext, Task
@@ -179,7 +179,7 @@ class DurableAgentExecutor(ABC, Generic[TaskT]):
         Returns:
             AgentResponse: Acceptance response with correlation ID
         """
-        acceptance_message = ChatMessage(
+        acceptance_message = Message(
             role="system",
             contents=[
                 Content.from_text(
@@ -360,7 +360,7 @@ class ClientAgentExecutor(DurableAgentExecutor[AgentResponse]):
                     "[ClientAgentExecutor] Error converting response for correlation: %s",
                     correlation_id,
                 )
-                error_message = ChatMessage(
+                error_message = Message(
                     role="system",
                     contents=[
                         Content.from_error(
@@ -375,7 +375,7 @@ class ClientAgentExecutor(DurableAgentExecutor[AgentResponse]):
                 self.max_poll_retries,
                 correlation_id,
             )
-            error_message = ChatMessage(
+            error_message = Message(
                 role="system",
                 contents=[
                     Content.from_error(

python/packages/durabletask/agent_framework_durabletask/_shim.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import Any, Generic, Literal, TypeVar
 
-from agent_framework import AgentThread, ChatMessage, SupportsAgentRun
+from agent_framework import AgentThread, Message, SupportsAgentRun
 
 from ._executors import DurableAgentExecutor
 from ._models import DurableAgentThread
@@ -86,7 +86,7 @@ class DurableAIAgent(SupportsAgentRun, Generic[TaskT]):
 
     def run(  # type: ignore[override]
         self,
-        messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
+        messages: str | Message | list[str] | list[Message] | None = None,
         *,
         stream: Literal[False] = False,
         thread: AgentThread | None = None,
@@ -136,7 +136,7 @@ class DurableAIAgent(SupportsAgentRun, Generic[TaskT]):
         """Create a new agent thread via the provider."""
         return self._executor.get_new_thread(self.name, **kwargs)
 
-    def _normalize_messages(self, messages: str | ChatMessage | list[str] | list[ChatMessage] | None) -> str:
+    def _normalize_messages(self, messages: str | Message | list[str] | list[Message] | None) -> str:
         """Convert supported message inputs to a single string.
 
         Args:
@@ -149,7 +149,7 @@ class DurableAIAgent(SupportsAgentRun, Generic[TaskT]):
             return ""
         if isinstance(messages, str):
             return messages
-        if isinstance(messages, ChatMessage):
+        if isinstance(messages, Message):
             return messages.text or ""
         if isinstance(messages, list):
             if not messages:
@@ -157,6 +157,6 @@ class DurableAIAgent(SupportsAgentRun, Generic[TaskT]):
             first_item = messages[0]
             if isinstance(first_item, str):
                 return "\n".join(messages)  # type: ignore[arg-type]
-            # List of ChatMessage
+            # List of Message
             return "\n".join([msg.text or "" for msg in messages])  # type: ignore[union-attr]
         return ""

python/packages/durabletask/agent_framework_durabletask/_worker.py

@@ -29,7 +29,7 @@ class DurableAIAgentWorker:
     Example:
         ```python
         from durabletask import TaskHubGrpcWorker
-        from agent_framework import ChatAgent
+        from agent_framework import Agent
         from agent_framework.azure import DurableAIAgentWorker
 
         # Create the underlying worker
@@ -39,7 +39,7 @@ class DurableAIAgentWorker:
         agent_worker = DurableAIAgentWorker(worker)
 
         # Register agents
-        my_agent = ChatAgent(chat_client=client, name="assistant")
+        my_agent = Agent(client=client, name="assistant")
         agent_worker.add_agent(my_agent)
 
         # Start the worker

python/packages/durabletask/tests/test_durable_entities.py

@@ -11,7 +11,7 @@ from typing import Any, TypeVar
 from unittest.mock import AsyncMock, Mock
 
 import pytest
-from agent_framework import AgentResponse, AgentResponseUpdate, ChatMessage, Content, ResponseStream
+from agent_framework import AgentResponse, AgentResponseUpdate, Content, Message, ResponseStream
 from pydantic import BaseModel
 
 from agent_framework_durabletask import (
@@ -71,7 +71,7 @@ def _make_entity(agent: Any, callback: Any = None, *, thread_id: str = "test-thr
 
 
 def _role_value(chat_message: DurableAgentStateMessage) -> str:
-    """Helper to extract the string role from a ChatMessage."""
+    """Helper to extract the string role from a Message."""
     role = getattr(chat_message, "role", None)
     role_value = getattr(role, "value", role)
     if role_value is None:
@@ -81,7 +81,7 @@ def _role_value(chat_message: DurableAgentStateMessage) -> str:
 
 def _agent_response(text: str | None) -> AgentResponse:
     """Create an AgentResponse with a single assistant message."""
-    message = ChatMessage(role="assistant", text=text) if text is not None else ChatMessage(role="assistant", text="")
+    message = Message(role="assistant", text=text) if text is not None else Message(role="assistant", text="")
     return AgentResponse(messages=[message], created_at="2024-01-01T00:00:00Z")
 
 

python/packages/durabletask/tests/test_shim.py

@@ -10,7 +10,7 @@ from typing import Any
 from unittest.mock import Mock
 
 import pytest
-from agent_framework import ChatMessage, SupportsAgentRun
+from agent_framework import Message, SupportsAgentRun
 from pydantic import BaseModel
 
 from agent_framework_durabletask import DurableAgentThread
@@ -76,8 +76,8 @@ class TestDurableAIAgentMessageNormalization:
         assert kwargs["run_request"].message == "Hello, world!"
 
     def test_run_accepts_chat_message(self, test_agent: DurableAIAgent[Any], mock_executor: Mock) -> None:
-        """Verify run accepts and normalizes ChatMessage objects."""
-        chat_msg = ChatMessage(role="user", text="Test message")
+        """Verify run accepts and normalizes Message objects."""
+        chat_msg = Message(role="user", text="Test message")
         test_agent.run(chat_msg)
 
         mock_executor.run_durable_agent.assert_called_once()
@@ -93,10 +93,10 @@ class TestDurableAIAgentMessageNormalization:
         assert kwargs["run_request"].message == "First message\nSecond message"
 
     def test_run_accepts_list_of_chat_messages(self, test_agent: DurableAIAgent[Any], mock_executor: Mock) -> None:
-        """Verify run accepts and joins list of ChatMessage objects."""
+        """Verify run accepts and joins list of Message objects."""
         messages = [
-            ChatMessage(role="user", text="Message 1"),
-            ChatMessage(role="assistant", text="Message 2"),
+            Message(role="user", text="Message 1"),
+            Message(role="assistant", text="Message 2"),
         ]
         test_agent.run(messages)