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-10 23:04:32 +00:00
parent a4c9e43afb
commit 0521f5bed8
418 changed files with 5385 additions and 5389 deletions
@@ -6,7 +6,7 @@ from unittest.mock import AsyncMock, MagicMock, patch

 import pytest
 from agent_framework import (
-    ChatAgent,
+    Agent,
    Content,
    HostedCodeInterpreterTool,
    HostedFileSearchTool,
@@ -16,7 +16,9 @@ from agent_framework import (
 )
 from agent_framework.exceptions import ServiceInitializationError
 from azure.ai.agents.models import (
-    Agent,
+    Agent as AzureAgent,
+)
+from azure.ai.agents.models import (
    CodeInterpreterToolDefinition,
 )
 from azure.identity.aio import AzureCliCredential
@@ -156,7 +158,7 @@ async def test_create_agent_basic(
    mock_agents_client: MagicMock,
 ) -> None:
    """Test creating a basic agent."""
-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "test-agent-id"
    mock_agent.name = "TestAgent"
    mock_agent.description = "A test agent"
@@ -175,7 +177,7 @@ async def test_create_agent_basic(
        description="A test agent",
    )

-    assert isinstance(agent, ChatAgent)
+    assert isinstance(agent, Agent)
    assert agent.name == "TestAgent"
    assert agent.id == "test-agent-id"
    mock_agents_client.create_agent.assert_called_once()
@@ -186,7 +188,7 @@ async def test_create_agent_with_model(
    mock_agents_client: MagicMock,
 ) -> None:
    """Test creating an agent with explicit model."""
-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "test-agent-id"
    mock_agent.name = "TestAgent"
    mock_agent.description = None
@@ -210,7 +212,7 @@ async def test_create_agent_with_tools(
    mock_agents_client: MagicMock,
 ) -> None:
    """Test creating an agent with tools."""
-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "test-agent-id"
    mock_agent.name = "TestAgent"
    mock_agent.description = None
@@ -245,7 +247,7 @@ async def test_create_agent_with_response_format(
        temperature: float
        description: str

-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "test-agent-id"
    mock_agent.name = "TestAgent"
    mock_agent.description = None
@@ -297,7 +299,7 @@ async def test_get_agent_by_id(
    mock_agents_client: MagicMock,
 ) -> None:
    """Test getting an agent by ID."""
-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "existing-agent-id"
    mock_agent.name = "ExistingAgent"
    mock_agent.description = "An existing agent"
@@ -312,7 +314,7 @@ async def test_get_agent_by_id(

    agent = await provider.get_agent("existing-agent-id")

-    assert isinstance(agent, ChatAgent)
+    assert isinstance(agent, Agent)
    assert agent.id == "existing-agent-id"
    mock_agents_client.get_agent.assert_called_once_with("existing-agent-id")

@@ -327,7 +329,7 @@ async def test_get_agent_with_function_tools(
    mock_function_tool.function = MagicMock()
    mock_function_tool.function.name = "get_weather"

-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "agent-with-tools"
    mock_agent.name = "AgentWithTools"
    mock_agent.description = None
@@ -356,7 +358,7 @@ async def test_get_agent_with_provided_function_tools(
    mock_function_tool.function = MagicMock()
    mock_function_tool.function.name = "get_weather"

-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "agent-with-tools"
    mock_agent.name = "AgentWithTools"
    mock_agent.description = None
@@ -376,7 +378,7 @@ async def test_get_agent_with_provided_function_tools(

    agent = await provider.get_agent("agent-with-tools", tools=get_weather)

-    assert isinstance(agent, ChatAgent)
+    assert isinstance(agent, Agent)
    assert agent.id == "agent-with-tools"


@@ -391,7 +393,7 @@ def test_as_agent_wraps_without_http(
    mock_agents_client: MagicMock,
 ) -> None:
    """Test as_agent wraps Agent object without making HTTP calls."""
-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "wrap-agent-id"
    mock_agent.name = "WrapAgent"
    mock_agent.description = "Wrapped agent"
@@ -405,7 +407,7 @@ def test_as_agent_wraps_without_http(

    agent = provider.as_agent(mock_agent)

-    assert isinstance(agent, ChatAgent)
+    assert isinstance(agent, Agent)
    assert agent.id == "wrap-agent-id"
    assert agent.name == "WrapAgent"
    # Ensure no HTTP calls were made
@@ -423,7 +425,7 @@ def test_as_agent_with_function_tools_validates(
    mock_function_tool.function = MagicMock()
    mock_function_tool.function.name = "my_function"

-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "agent-id"
    mock_agent.name = "Agent"
    mock_agent.description = None
@@ -449,7 +451,7 @@ def test_as_agent_with_hosted_tools(
    mock_code_interpreter = MagicMock()
    mock_code_interpreter.type = "code_interpreter"

-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "agent-id"
    mock_agent.name = "Agent"
    mock_agent.description = None
@@ -463,7 +465,7 @@ def test_as_agent_with_hosted_tools(

    agent = provider.as_agent(mock_agent)

-    assert isinstance(agent, ChatAgent)
+    assert isinstance(agent, Agent)
    # Should have HostedCodeInterpreterTool in the default_options tools
    assert any(isinstance(t, HostedCodeInterpreterTool) for t in (agent.default_options.get("tools") or []))  # type: ignore

@@ -483,7 +485,7 @@ def test_as_agent_with_dict_function_tools_validates(
        },
    }

-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "agent-id"
    mock_agent.name = "Agent"
    mock_agent.description = None
@@ -515,7 +517,7 @@ def test_as_agent_with_dict_function_tools_provided(
        },
    }

-    mock_agent = MagicMock(spec=Agent)
+    mock_agent = MagicMock(spec=AzureAgent)
    mock_agent.id = "agent-id"
    mock_agent.name = "Agent"
    mock_agent.description = None
@@ -534,7 +536,7 @@ def test_as_agent_with_dict_function_tools_provided(

    agent = provider.as_agent(mock_agent, tools=dict_based_function)

-    assert isinstance(agent, ChatAgent)
+    assert isinstance(agent, Agent)
    assert agent.id == "agent-id"


@@ -810,7 +812,7 @@ async def test_integration_create_agent() -> None:
        )

        try:
-            assert isinstance(agent, ChatAgent)
+            assert isinstance(agent, Agent)
            assert agent.name == "IntegrationTestAgent"
            assert agent.id is not None
        finally:
@@ -837,7 +839,7 @@ async def test_integration_get_agent() -> None:
            # Then get it using the provider
            agent = await provider.get_agent(created.id)

-            assert isinstance(agent, ChatAgent)
+            assert isinstance(agent, Agent)
            assert agent.id == created.id
        finally:
            await provider._agents_client.delete_agent(created.id)  # type: ignore
@@ -11,10 +11,8 @@ from uuid import uuid4

 import pytest
 from agent_framework import (
+    Agent,
    AgentResponse,
-    ChatAgent,
-    ChatClientProtocol,
-    ChatMessage,
    ChatOptions,
    ChatResponse,
    Content,
@@ -22,6 +20,8 @@ from agent_framework import (
    HostedFileSearchTool,
    HostedMCPTool,
    HostedWebSearchTool,
+    Message,
+    SupportsChatGetResponse,
    tool,
 )
 from agent_framework.exceptions import ServiceInitializationError
@@ -88,19 +88,19 @@ async def temporary_chat_client(agent_name: str) -> AsyncIterator[AzureAIClient]
    """Async context manager that creates an Azure AI agent and yields an `AzureAIClient`.

    The underlying agent version is cleaned up automatically after use.
-    Tests can construct their own `ChatAgent` instances from the yielded client.
+    Tests can construct their own `Agent` instances from the yielded client.
    """
    endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
    async with (
        AzureCliCredential() as credential,
        AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    ):
-        chat_client = AzureAIClient(
+        client = AzureAIClient(
            project_client=project_client,
            agent_name=agent_name,
        )
        try:
-            yield chat_client
+            yield client
        finally:
            await project_client.agents.delete(agent_name=agent_name)

@@ -179,7 +179,7 @@ def test_init_with_project_client(mock_project_client: MagicMock) -> None:
        assert client.agent_name == "test-agent"
        assert client.agent_version == "1.0"
        assert not client._should_close_client  # type: ignore
-        assert isinstance(client, ChatClientProtocol)
+        assert isinstance(client, SupportsChatGetResponse)


 def test_init_auto_create_client(
@@ -298,9 +298,9 @@ async def test_prepare_messages_for_azure_ai_with_system_messages(
    client = create_test_azure_ai_client(mock_project_client)

    messages = [
-        ChatMessage(role="system", contents=[Content.from_text(text="You are a helpful assistant.")]),
-        ChatMessage(role="user", contents=[Content.from_text(text="Hello")]),
-        ChatMessage(role="assistant", contents=[Content.from_text(text="System response")]),
+        Message(role="system", contents=[Content.from_text(text="You are a helpful assistant.")]),
+        Message(role="user", contents=[Content.from_text(text="Hello")]),
+        Message(role="assistant", contents=[Content.from_text(text="System response")]),
    ]

    result_messages, instructions = client._prepare_messages_for_azure_ai(messages)  # type: ignore
@@ -318,8 +318,8 @@ async def test_prepare_messages_for_azure_ai_no_system_messages(
    client = create_test_azure_ai_client(mock_project_client)

    messages = [
-        ChatMessage(role="user", contents=[Content.from_text(text="Hello")]),
-        ChatMessage(role="assistant", contents=[Content.from_text(text="Hi there!")]),
+        Message(role="user", contents=[Content.from_text(text="Hello")]),
+        Message(role="assistant", contents=[Content.from_text(text="Hi there!")]),
    ]

    result_messages, instructions = client._prepare_messages_for_azure_ai(messages)  # type: ignore
@@ -419,7 +419,7 @@ async def test_prepare_options_basic(mock_project_client: MagicMock) -> None:
    """Test prepare_options basic functionality."""
    client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent", agent_version="1.0")

-    messages = [ChatMessage(role="user", contents=[Content.from_text(text="Hello")])]
+    messages = [Message(role="user", contents=[Content.from_text(text="Hello")])]

    with (
        patch(
@@ -456,7 +456,7 @@ async def test_prepare_options_with_application_endpoint(
        agent_version="1",
    )

-    messages = [ChatMessage(role="user", contents=[Content.from_text(text="Hello")])]
+    messages = [Message(role="user", contents=[Content.from_text(text="Hello")])]

    with (
        patch(
@@ -498,7 +498,7 @@ async def test_prepare_options_with_application_project_client(
        agent_version="1",
    )

-    messages = [ChatMessage(role="user", contents=[Content.from_text(text="Hello")])]
+    messages = [Message(role="user", contents=[Content.from_text(text="Hello")])]

    with (
        patch(
@@ -977,7 +977,7 @@ async def test_prepare_options_excludes_response_format(
    """Test that prepare_options excludes response_format, text, and text_format from final run options."""
    client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent", agent_version="1.0")

-    messages = [ChatMessage(role="user", contents=[Content.from_text(text="Hello")])]
+    messages = [Message(role="user", contents=[Content.from_text(text="Hello")])]
    chat_options: ChatOptions = {}

    with (
@@ -1363,10 +1363,10 @@ async def test_integration_options(
    # Prepare test message
    if option_name.startswith("tool_choice"):
        # Use weather-related prompt for tool tests
-        messages = [ChatMessage(role="user", text="What is the weather in Seattle?")]
+        messages = [Message(role="user", text="What is the weather in Seattle?")]
    else:
        # Generic prompt for simple options
-        messages = [ChatMessage(role="user", text="Say 'Hello World' briefly.")]
+        messages = [Message(role="user", text="Say 'Hello World' briefly.")]

    # Build options dict
    options: dict[str, Any] = {option_name: option_value, "tools": [get_weather]}
@@ -1480,11 +1480,11 @@ async def test_integration_agent_options(
            # Prepare test message
            if option_name.startswith("response_format"):
                # Use prompt that works well with structured output
-                messages = [ChatMessage(role="user", text="The weather in Seattle is sunny")]
-                messages.append(ChatMessage(role="user", text="What is the weather in Seattle?"))
+                messages = [Message(role="user", text="The weather in Seattle is sunny")]
+                messages.append(Message(role="user", text="What is the weather in Seattle?"))
            else:
                # Generic prompt for simple options
-                messages = [ChatMessage(role="user", text="Say 'Hello World' briefly.")]
+                messages = [Message(role="user", text="Say 'Hello World' briefly.")]

            # Build options dict
            options = {option_name: option_value}
@@ -1621,8 +1621,8 @@ async def test_integration_agent_existing_thread():

    async with (
        temporary_chat_client(agent_name="af-int-test-existing-thread") as client,
-        ChatAgent(
-            chat_client=client,
+        Agent(
+            client=client,
            instructions="You are a helpful assistant with good memory.",
        ) as first_agent,
    ):
@@ -1640,8 +1640,8 @@ async def test_integration_agent_existing_thread():
    if preserved_thread:
        async with (
            temporary_chat_client(agent_name="af-int-test-existing-thread-2") as client,
-            ChatAgent(
-                chat_client=client,
+            Agent(
+                client=client,
                instructions="You are a helpful assistant with good memory.",
            ) as second_agent,
        ):
@@ -4,7 +4,7 @@ import os
 from unittest.mock import AsyncMock, MagicMock, patch

 import pytest
-from agent_framework import ChatAgent, FunctionTool
+from agent_framework import Agent, FunctionTool
 from agent_framework._mcp import MCPTool
 from agent_framework.exceptions import ServiceInitializationError
 from azure.ai.projects.aio import AIProjectClient
@@ -158,7 +158,7 @@ async def test_provider_create_agent(
            description="Test Agent",
        )

-        assert isinstance(agent, ChatAgent)
+        assert isinstance(agent, Agent)
        assert agent.name == "test-agent"
        mock_project_client.agents.create_version.assert_called_once()

@@ -192,7 +192,7 @@ async def test_provider_create_agent_with_env_model(
        # Call without model parameter - should use env var
        agent = await provider.create_agent(name="test-agent")

-        assert isinstance(agent, ChatAgent)
+        assert isinstance(agent, Agent)
        # Verify the model from env var was used
        call_args = mock_project_client.agents.create_version.call_args
        assert call_args[1]["definition"].model == azure_ai_unit_test_env["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
@@ -322,7 +322,7 @@ async def test_provider_get_agent_with_name(mock_project_client: MagicMock) -> N

    agent = await provider.get_agent(name="test-agent")

-    assert isinstance(agent, ChatAgent)
+    assert isinstance(agent, Agent)
    assert agent.name == "test-agent"
    mock_project_client.agents.get.assert_called_with(agent_name="test-agent")

@@ -350,7 +350,7 @@ async def test_provider_get_agent_with_reference(mock_project_client: MagicMock)
    agent_reference = AgentReference(name="test-agent", version="1.0")
    agent = await provider.get_agent(reference=agent_reference)

-    assert isinstance(agent, ChatAgent)
+    assert isinstance(agent, Agent)
    assert agent.name == "test-agent"
    mock_project_client.agents.get_version.assert_called_with(agent_name="test-agent", agent_version="1.0")

@@ -410,7 +410,7 @@ def test_provider_as_agent(mock_project_client: MagicMock) -> None:
    with patch("agent_framework_azure_ai._project_provider.AzureAIClient") as mock_azure_ai_client:
        agent = provider.as_agent(mock_agent_version)

-        assert isinstance(agent, ChatAgent)
+        assert isinstance(agent, Agent)
        assert agent.name == "test-agent"
        assert agent.description == "Test Agent"

@@ -709,7 +709,7 @@ async def test_provider_create_and_get_agent_integration() -> None:
                instructions="You are a helpful assistant. Always respond with 'Hello from provider!'",
            )

-            assert isinstance(agent, ChatAgent)
+            assert isinstance(agent, Agent)
            assert agent.name == "ProviderTestAgent"

            # Run the agent