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/samples/getting_started/observability/advanced_zero_code.py

@@ -12,7 +12,7 @@ from opentelemetry.trace.span import format_trace_id
 from pydantic import Field
 
 if TYPE_CHECKING:
-    from agent_framework import ChatClientProtocol
+    from agent_framework import SupportsChatGetResponse
 
 
 """
@@ -51,7 +51,7 @@ async def get_weather(
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
 
 
-async def run_chat_client(client: "ChatClientProtocol", stream: bool = False) -> None:
+async def run_chat_client(client: "SupportsChatGetResponse", stream: bool = False) -> None:
     """Run an AI service.
 
     This function runs an AI service and prints the output.

python/samples/getting_started/observability/agent_observability.py

@@ -4,7 +4,7 @@ import asyncio
 from random import randint
 from typing import Annotated
 
-from agent_framework import ChatAgent, tool
+from agent_framework import Agent, tool
 from agent_framework.observability import configure_otel_providers, get_tracer
 from agent_framework.openai import OpenAIChatClient
 from opentelemetry.trace import SpanKind
@@ -39,8 +39,8 @@ async def main():
     with get_tracer().start_as_current_span("Scenario: Agent Chat", kind=SpanKind.CLIENT) as current_span:
         print(f"Trace ID: {format_trace_id(current_span.get_span_context().trace_id)}")
 
-        agent = ChatAgent(
-            chat_client=OpenAIChatClient(),
+        agent = Agent(
+            client=OpenAIChatClient(),
             tools=get_weather,
             name="WeatherAgent",
             instructions="You are a weather assistant.",

python/samples/getting_started/observability/agent_with_foundry_tracing.py

@@ -16,7 +16,7 @@ from random import randint
 from typing import Annotated
 
 import dotenv
-from agent_framework import ChatAgent, tool
+from agent_framework import Agent, tool
 from agent_framework.observability import create_resource, enable_instrumentation, get_tracer
 from agent_framework.openai import OpenAIResponsesClient
 from azure.ai.projects.aio import AIProjectClient
@@ -30,7 +30,7 @@ from pydantic import Field
 This sample shows you can can setup telemetry in Microsoft Foundry for a custom agent.
 First ensure you have a Foundry workspace with Application Insights enabled.
 And use the Operate tab to Register an Agent.
-Set the OpenTelemetry agent ID to the value used below in the ChatAgent creation: `weather-agent` (or change both).
+Set the OpenTelemetry agent ID to the value used below in the Agent creation: `weather-agent` (or change both).
 The sample uses the Azure Monitor OpenTelemetry exporter to send traces to Application Insights.
 So ensure you have the `azure-monitor-opentelemetry` package installed.
 """
@@ -85,8 +85,8 @@ async def main():
         with get_tracer().start_as_current_span("Weather Agent Chat", kind=SpanKind.CLIENT) as current_span:
             print(f"Trace ID: {format_trace_id(current_span.get_span_context().trace_id)}")
 
-            agent = ChatAgent(
-                chat_client=OpenAIResponsesClient(),
+            agent = Agent(
+                client=OpenAIResponsesClient(),
                 tools=get_weather,
                 name="WeatherAgent",
                 instructions="You are a weather assistant.",

python/samples/getting_started/observability/azure_ai_agent_observability.py

@@ -6,7 +6,7 @@ from random import randint
 from typing import Annotated
 
 import dotenv
-from agent_framework import ChatAgent, tool
+from agent_framework import Agent, tool
 from agent_framework.azure import AzureAIClient
 from agent_framework.observability import get_tracer
 from azure.ai.projects.aio import AIProjectClient
@@ -56,8 +56,8 @@ async def main():
         with get_tracer().start_as_current_span("Single Agent Chat", kind=SpanKind.CLIENT) as current_span:
             print(f"Trace ID: {format_trace_id(current_span.get_span_context().trace_id)}")
 
-            agent = ChatAgent(
-                chat_client=client,
+            agent = Agent(
+                client=client,
                 tools=get_weather,
                 name="WeatherAgent",
                 instructions="You are a weather assistant.",

python/samples/getting_started/observability/configure_otel_providers_with_env_var.py

@@ -14,7 +14,7 @@ from opentelemetry.trace.span import format_trace_id
 from pydantic import Field
 
 if TYPE_CHECKING:
-    from agent_framework import ChatClientProtocol
+    from agent_framework import SupportsChatGetResponse
 
 """
 This sample, show how you can configure observability of an application via the
@@ -28,7 +28,7 @@ output traces, logs, and metrics to the console.
 """
 
 # Define the scenarios that can be run to show the telemetry data collected by the SDK
-SCENARIOS = ["chat_client", "chat_client_stream", "tool", "all"]
+SCENARIOS = ["client", "client_stream", "tool", "all"]
 
 
 # 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.
@@ -42,7 +42,7 @@ async def get_weather(
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
 
 
-async def run_chat_client(client: "ChatClientProtocol", stream: bool = False) -> None:
+async def run_chat_client(client: "SupportsChatGetResponse", stream: bool = False) -> None:
     """Run an AI service.
 
     This function runs an AI service and prints the output.
@@ -97,7 +97,7 @@ async def run_tool() -> None:
         print(f"Weather in Amsterdam:\n{weather}")
 
 
-async def main(scenario: Literal["chat_client", "chat_client_stream", "tool", "all"] = "all"):
+async def main(scenario: Literal["client", "client_stream", "tool", "all"] = "all"):
     """Run the selected scenario(s)."""
 
     # This will enable tracing and create the necessary tracing, logging and metrics providers
@@ -113,10 +113,10 @@ async def main(scenario: Literal["chat_client", "chat_client_stream", "tool", "a
         if scenario == "tool" or scenario == "all":
             with suppress(Exception):
                 await run_tool()
-        if scenario == "chat_client_stream" or scenario == "all":
+        if scenario == "client_stream" or scenario == "all":
             with suppress(Exception):
                 await run_chat_client(client, stream=True)
-        if scenario == "chat_client" or scenario == "all":
+        if scenario == "client" or scenario == "all":
             with suppress(Exception):
                 await run_chat_client(client, stream=False)
 

python/samples/getting_started/observability/configure_otel_providers_with_parameters.py

@@ -14,7 +14,7 @@ from opentelemetry.trace.span import format_trace_id
 from pydantic import Field
 
 if TYPE_CHECKING:
-    from agent_framework import ChatClientProtocol
+    from agent_framework import SupportsChatGetResponse
 
 """
 This sample shows how you can configure observability with custom exporters passed directly
@@ -28,7 +28,7 @@ Use this approach when you need custom exporter configuration beyond what enviro
 """
 
 # Define the scenarios that can be run to show the telemetry data collected by the SDK
-SCENARIOS = ["chat_client", "chat_client_stream", "tool", "all"]
+SCENARIOS = ["client", "client_stream", "tool", "all"]
 
 
 # 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.
@@ -42,7 +42,7 @@ async def get_weather(
     return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
 
 
-async def run_chat_client(client: "ChatClientProtocol", stream: bool = False) -> None:
+async def run_chat_client(client: "SupportsChatGetResponse", stream: bool = False) -> None:
     """Run an AI service.
 
     This function runs an AI service and prints the output.
@@ -97,7 +97,7 @@ async def run_tool() -> None:
         print(f"Weather in Amsterdam:\n{weather}")
 
 
-async def main(scenario: Literal["chat_client", "chat_client_stream", "tool", "all"] = "all"):
+async def main(scenario: Literal["client", "client_stream", "tool", "all"] = "all"):
     """Run the selected scenario(s)."""
 
     # Setup the logging with the more complete format
@@ -148,10 +148,10 @@ async def main(scenario: Literal["chat_client", "chat_client_stream", "tool", "a
         if scenario == "tool" or scenario == "all":
             with suppress(Exception):
                 await run_tool()
-        if scenario == "chat_client_stream" or scenario == "all":
+        if scenario == "client_stream" or scenario == "all":
             with suppress(Exception):
                 await run_chat_client(client, stream=True)
-        if scenario == "chat_client" or scenario == "all":
+        if scenario == "client" or scenario == "all":
             with suppress(Exception):
                 await run_chat_client(client, stream=False)