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>
2026-06-16 21:04:09 +08:00 · 2026-02-11 00:04:32 +01:00
parent a4c9e43afb
commit 0521f5bed8
418 changed files with 5385 additions and 5389 deletions
@@ -44,7 +44,7 @@ Each agent/workflow follows a strict structure required by DevUI's discovery sys

 ```
 agent_name/
-├── __init__.py      # Must export: agent = ChatAgent(...)
+├── __init__.py      # Must export: agent = Agent(...)
 ├── agent.py         # Agent implementation
 └── .env.example     # Example environment variables
 ```
@@ -100,13 +100,13 @@ Example:

 ```python
 # my_agent/__init__.py
-from agent_framework import ChatAgent
+from agent_framework import Agent
 from agent_framework.openai import OpenAIChatClient

-agent = ChatAgent(
+agent = Agent(
    name="MyAgent",
    description="My custom agent",
-    chat_client=OpenAIChatClient(),
+    client=OpenAIChatClient(),
    # ... your configuration
 )
 ```
@@ -21,7 +21,7 @@ import logging
 import os
 from typing import Annotated

-from agent_framework import ChatAgent, tool
+from agent_framework import Agent, tool
 from agent_framework.azure import AzureOpenAIResponsesClient

 logger = logging.getLogger(__name__)
@@ -68,7 +68,7 @@ def extract_key_points(


 # Agent using Azure OpenAI Responses API (supports PDF uploads!)
-agent = ChatAgent(
+agent = Agent(
    name="AzureResponsesAgent",
    description="An agent that can analyze PDFs, images, and other documents using Azure OpenAI Responses API",
    instructions="""
@@ -85,7 +85,7 @@ agent = ChatAgent(
    For PDFs, you can read and understand the text, tables, and structure.
    For images, you can describe what you see and extract any text.
    """,
-    chat_client=AzureOpenAIResponsesClient(
+    client=AzureOpenAIResponsesClient(
        deployment_name=_deployment_name,
        endpoint=_endpoint,
        api_version="2025-03-01-preview",  # Required for Responses API
@@ -8,7 +8,7 @@ Make sure to run 'az login' before starting devui.
 import os
 from typing import Annotated

-from agent_framework import ChatAgent, tool
+from agent_framework import Agent, tool
 from agent_framework.azure import AzureAIAgentClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
@@ -43,9 +43,9 @@ def get_forecast(


 # Agent instance following Agent Framework conventions
-agent = ChatAgent(
+agent = Agent(
    name="FoundryWeatherAgent",
-    chat_client=AzureAIAgentClient(
+    client=AzureAIAgentClient(
        project_endpoint=os.environ.get("AZURE_AI_PROJECT_ENDPOINT"),
        model_deployment_name=os.environ.get("FOUNDRY_MODEL_DEPLOYMENT_NAME"),
        credential=AzureCliCredential(),
@@ -10,7 +10,7 @@ import logging
 import os
 from typing import Annotated

-from agent_framework import ChatAgent, Executor, WorkflowBuilder, WorkflowContext, handler, tool
+from agent_framework import Agent, Executor, WorkflowBuilder, WorkflowContext, handler, tool
 from agent_framework.azure import AzureOpenAIChatClient
 from agent_framework.devui import serve
 from typing_extensions import Never
@@ -68,7 +68,7 @@ def main():
    logger = logging.getLogger(__name__)

    # Create Azure OpenAI chat client
-    chat_client = AzureOpenAIChatClient(
+    client = AzureOpenAIChatClient(
        api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
        azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
        api_version=os.environ.get("AZURE_OPENAI_API_VERSION", "2024-10-21"),
@@ -76,22 +76,22 @@ def main():
    )

    # Create agents
-    weather_agent = ChatAgent(
+    weather_agent = Agent(
        name="weather-assistant",
        description="Provides weather information and time",
        instructions=(
            "You are a helpful weather and time assistant. Use the available tools to "
            "provide accurate weather information and current time for any location."
        ),
-        chat_client=chat_client,
+        client=client,
        tools=[get_weather, get_time],
    )

-    simple_agent = ChatAgent(
+    simple_agent = Agent(
        name="general-assistant",
        description="A simple conversational agent",
        instructions="You are a helpful assistant.",
-        chat_client=chat_client,
+        client=client,
    )

    # Create a basic workflow: Input -> UpperCase -> AddExclamation -> Output
@@ -7,15 +7,16 @@ from collections.abc import AsyncIterable, Awaitable, Callable
 from typing import Annotated

 from agent_framework import (
-    ChatAgent,
+    Agent,
    ChatContext,
-    ChatMessage,
    ChatResponse,
    ChatResponseUpdate,
    Content,
    FunctionInvocationContext,
+    Message,
    MiddlewareTermination,
    ResponseStream,
+    Role,
    chat_middleware,
    function_middleware,
    tool,
@@ -44,7 +45,7 @@ async def security_filter_middleware(

    # Check only the last message (most recent user input)
    last_message = context.messages[-1] if context.messages else None
-    if last_message and last_message.role == "user" and last_message.text:
+    if last_message and last_message.role == Role.USER and last_message.text:
        message_lower = last_message.text.lower()
        for term in blocked_terms:
            if term in message_lower:
@@ -55,26 +56,29 @@ async def security_filter_middleware(
                )

                if context.stream:
-                    # Streaming mode: return async generator
+                    # Streaming mode: wrap in ResponseStream
                    async def blocked_stream(msg: str = error_message) -> AsyncIterable[ChatResponseUpdate]:
                        yield ChatResponseUpdate(
                            contents=[Content.from_text(text=msg)],
-                            role="assistant",
+                            role=Role.ASSISTANT,
                        )

-                    context.result = ResponseStream(blocked_stream(), finalizer=ChatResponse.from_updates)
+                    response = ChatResponse(
+                        messages=[Message(role=Role.ASSISTANT, text=error_message)]
+                    )
+                    context.result = ResponseStream(blocked_stream(), finalizer=lambda _, r=response: r)
                else:
                    # Non-streaming mode: return complete response
                    context.result = ChatResponse(
                        messages=[
-                            ChatMessage(
-                                role="assistant",
+                            Message(
+                                role=Role.ASSISTANT,
                                text=error_message,
                            )
                        ]
                    )

-                raise MiddlewareTermination
+                raise MiddlewareTermination(result=context.result)

    await call_next(context)

@@ -92,7 +96,7 @@ async def atlantis_location_filter_middleware(
            "Blocked! Hold up right there!! Tell the user that "
            "'Atlantis is a special place, we must never ask about the weather there!!'"
        )
-        raise MiddlewareTermination
+        raise MiddlewareTermination(result=context.result)

    await call_next(context)

@@ -136,7 +140,7 @@ def send_email(


 # Agent instance following Agent Framework conventions
-agent = ChatAgent(
+agent = Agent(
    name="AzureWeatherAgent",
    description="A helpful agent that provides weather information and forecasts",
    instructions="""
@@ -144,7 +148,7 @@ agent = ChatAgent(
    and forecasts for any location. Always be helpful and provide detailed
    weather information when asked.
    """,
-    chat_client=AzureOpenAIChatClient(
+    client=AzureOpenAIChatClient(
        api_key=os.environ.get("AZURE_OPENAI_API_KEY", ""),
    ),
    tools=[get_weather, get_forecast, send_email],
@@ -59,10 +59,10 @@ def is_approved(message: Any) -> bool:


 # Create Azure OpenAI chat client
-chat_client = AzureOpenAIChatClient(api_key=os.environ.get("AZURE_OPENAI_API_KEY", ""))
+client = AzureOpenAIChatClient(api_key=os.environ.get("AZURE_OPENAI_API_KEY", ""))

 # Create Writer agent - generates content
-writer = chat_client.as_agent(
+writer = client.as_agent(
    name="Writer",
    instructions=(
        "You are an excellent content writer. "
@@ -72,7 +72,7 @@ writer = chat_client.as_agent(
 )

 # Create Reviewer agent - evaluates and provides structured feedback
-reviewer = chat_client.as_agent(
+reviewer = client.as_agent(
    name="Reviewer",
    instructions=(
        "You are an expert content reviewer. "
@@ -90,7 +90,7 @@ reviewer = chat_client.as_agent(
 )

 # Create Editor agent - improves content based on feedback
-editor = chat_client.as_agent(
+editor = client.as_agent(
    name="Editor",
    instructions=(
        "You are a skilled editor. "
@@ -101,7 +101,7 @@ editor = chat_client.as_agent(
 )

 # Create Publisher agent - formats content for publication
-publisher = chat_client.as_agent(
+publisher = client.as_agent(
    name="Publisher",
    instructions=(
        "You are a publishing agent. "
@@ -111,7 +111,7 @@ publisher = chat_client.as_agent(
 )

 # Create Summarizer agent - creates final publication report
-summarizer = chat_client.as_agent(
+summarizer = client.as_agent(
    name="Summarizer",
    instructions=(
        "You are a summarizer agent. "