Python: [BREAKING] Moved to a single get_response and run API (#3379)

* WIP * big update to new ResponseStream model * fixed tests and typing * fixed tests and typing * fixed tools typevar import * fix * mypy fix * mypy fixes and some cleanup * fix missing quoted names * and client * fix imports agui * fix anthropic override * fix agui * fix ag ui * fix import * fix anthropic types * fix mypy * refactoring * updated typing * fix 3.11 * fixes * redid layering of chat clients and agents * redid layering of chat clients and agents * Fix lint, type, and test issues after rebase - Add @overload decorators to AgentProtocol.run() for type compatibility - Add missing docstring params (middleware, function_invocation_configuration) - Fix TODO format (TD002) by adding author tags - Fix broken observability tests from upstream: - Replace non-existent use_instrumentation with direct instantiation - Replace non-existent use_agent_instrumentation with AgentTelemetryLayer mixin - Fix get_streaming_response to use get_response(stream=True) - Add AgentInitializationError import - Update streaming exception tests to match actual behavior * Fix AgentExecutionException import error in test_agents.py - Replace non-existent AgentExecutionException with AgentRunException * Fix test import and asyncio deprecation issues - Add 'tests' to pythonpath in ag-ui pyproject.toml for utils_test_ag_ui import - Replace deprecated asyncio.get_event_loop().run_until_complete with asyncio.run * Fix azure-ai test failures - Update _prepare_options patching to use correct class path - Fix test_to_azure_ai_agent_tools_web_search_missing_connection to clear env vars * Convert ag-ui utils_test_ag_ui.py to conftest.py - Move test utilities to conftest.py for proper pytest discovery - Update all test imports to use conftest instead of utils_test_ag_ui - Remove old utils_test_ag_ui.py file - Revert pythonpath change in pyproject.toml * fix: use relative imports for ag-ui test utilities * fix agui * Rename Bare*Client to Raw*Client and BaseChatClient - Renamed BareChatClient to BaseChatClient (abstract base class) - Renamed BareOpenAIChatClient to RawOpenAIChatClient - Renamed BareOpenAIResponsesClient to RawOpenAIResponsesClient - Renamed BareAzureAIClient to RawAzureAIClient - Added warning docstrings to Raw* classes about layer ordering - Updated README in samples/getting_started/agents/custom with layer docs - Added test for span ordering with function calling * Fix layer ordering: FunctionInvocationLayer before ChatTelemetryLayer This ensures each inner LLM call gets its own telemetry span, resulting in the correct span sequence: chat -> execute_tool -> chat Updated all production clients and test mocks to use correct ordering: - ChatMiddlewareLayer (first) - FunctionInvocationLayer (second) - ChatTelemetryLayer (third) - BaseChatClient/Raw...Client (fourth) * Remove run_stream usage * Fix conversation_id propagation * Python: Add BaseAgent implementation for Claude Agent SDK (#3509) * Added ClaudeAgent implementation * Updated streaming logic * Small updates * Small update * Fixes * Small fix * Naming improvements * Updated imports * Addressed comments * Updated package versions * Update Claude agent connector layering * fix test and plugin * Store function middleware in invocation layer * Fix telemetry streaming and ag-ui tests * Remove legacy ag-ui tests folder * updates * Remove terminate flag from FunctionInvocationContext, use MiddlewareTermination instead - Remove terminate attribute from FunctionInvocationContext - Add result attribute to MiddlewareTermination to carry function results - FunctionMiddlewarePipeline.execute() now lets MiddlewareTermination propagate - _auto_invoke_function captures context.result in exception before re-raising - _try_execute_function_calls catches MiddlewareTermination and sets should_terminate - Fix handoff middleware to append to chat_client.function_middleware directly - Update tests to use raise MiddlewareTermination instead of context.terminate - Add middleware flow documentation in samples/concepts/tools/README.md - Fix ag-ui to use FunctionMiddlewarePipeline instead of removed create_function_middleware_pipeline * fix: remove references to removed terminate flag in purview tests, add type ignore * fix: move _test_utils.py from package to test folder * fix: call get_final_response() to trigger context provider notification in streaming test * fix: correct broken links in tools README * docs: clarify default middleware behavior in summary table * fix: ensure inner stream result hooks are called when using map()/from_awaitable() * Fix mypy type errors * Address PR review comments on observability.py - Remove TODO comment about unconsumed streams, add explanatory note instead - Remove redundant _close_span cleanup hook (already called in _finalize_stream) - Clarify behavior: cleanup hooks run after stream iteration, if stream is not consumed the span remains open until garbage collected * Remove gen_ai.client.operation.duration from span attributes Duration is a metrics-only attribute per OpenTelemetry semantic conventions. It should be recorded to the histogram but not set as a span attribute. * Remove duration from _get_response_attributes, pass directly to _capture_response Duration is a metrics-only attribute. It's now passed directly to _capture_response instead of being included in the attributes dict that gets set on the span. * Remove redundant _close_span cleanup hook in AgentTelemetryLayer _finalize_stream already calls _close_span() in its finally block, so adding it as a separate cleanup hook is redundant. * Use weakref.finalize to close span when stream is garbage collected If a user creates a streaming response but never consumes it, the cleanup hooks won't run. Now we register a weak reference finalizer that will close the span when the stream object is garbage collected, ensuring spans don't leak in this scenario. * Fix _get_finalizers_from_stream to use _result_hooks attribute Renamed function to _get_result_hooks_from_stream and fixed it to look for the _result_hooks attribute which is the correct name in ResponseStream class. * Add missing asyncio import in test_request_info_mixin.py * Fix leftover merge conflict marker in image_generation sample * Update integration tests * Fix integration tests: increase max_iterations from 1 to 2 Tests with tool_choice options require at least 2 iterations: 1. First iteration to get function call and execute the tool 2. Second iteration to get the final text response With max_iterations=1, streaming tests would return early with only the function call/result but no final text content. * Fix duplicate function call error in conversation-based APIs When using conversation_id (for Responses/Assistants APIs), the server already has the function call message from the previous response. We should only send the new function result message, not all messages including the function call which would cause a duplicate ID error. Fix: When conversation_id is set, only send the last message (the tool result) instead of all response.messages. * Add regression test for conversation_id propagation between tool iterations Port test from PR #3664 with updates for new streaming API pattern. Tests that conversation_id is properly updated in options dict during function invocation loop iterations. * Fix tool_choice=required to return after tool execution When tool_choice is 'required', the user's intent is to force exactly one tool call. After the tool executes, return immediately with the function call and result - don't continue to call the model again. This fixes integration tests that were failing with empty text responses because with tool_choice=required, the model would keep returning function calls instead of text. Also adds regression tests for: - conversation_id propagation between tool iterations (from PR #3664) - tool_choice=required returns after tool execution * Document tool_choice behavior in tools README - Add table explaining tool_choice values (auto, none, required) - Explain why tool_choice=required returns immediately after tool execution - Add code example showing the difference between required and auto - Update flow diagram to show the early return path for tool_choice=required * Fix tool_choice=None behavior - don't default to 'auto' Remove the hardcoded default of 'auto' for tool_choice in ChatAgent init. When tool_choice is not specified (None), it will now not be sent to the API, allowing the API's default behavior to be used. Users who want tool_choice='auto' can still explicitly set it either in default_options or at runtime. Fixes #3585 * Fix tool_choice=none should not remove tools In OpenAI Assistants client, tools were not being sent when tool_choice='none'. This was incorrect - tool_choice='none' means the model won't call tools, but tools should still be available in the request (they may be used later in the conversation). Fixes #3585 * Add test for tool_choice=none preserving tools Adds a regression test to ensure that when tool_choice='none' is set but tools are provided, the tools are still sent to the API. This verifies the fix for #3585. * Fix tool_choice=none should not remove tools in all clients Apply the same fix to OpenAI Responses client and Azure AI client: - OpenAI Responses: Remove else block that popped tool_choice/parallel_tool_calls - Azure AI: Remove tool_choice != 'none' check when adding tools When tool_choice='none', the model won't call tools, but tools should still be sent to the API so they're available for future turns. Also update README to clarify tool_choice=required supports multiple tools. Fixes #3585 * Keep tool_choice even when tools is None Move tool_choice processing outside of the 'if tools' block in OpenAI Responses client so tool_choice is sent to the API even when no tools are provided. * Update test to match new parallel_tool_calls behavior Changed test_prepare_options_removes_parallel_tool_calls_when_no_tools to test_prepare_options_preserves_parallel_tool_calls_when_no_tools to reflect that parallel_tool_calls is now preserved even when no tools are present, consistent with the tool_choice behavior. * Fix ChatMessage API and Role enum usage after rebase - Update ChatMessage instantiation to use keyword args (role=, text=, contents=) - Fix Role enum comparisons to use .value for string comparison - Add created_at to AgentResponse in error handling - Fix AgentResponse.from_updates -> from_agent_run_response_updates - Fix DurableAgentStateMessage.from_chat_message to convert Role enum to string - Add Role import where needed * Fix additional ChatMessage API and method name changes - Fix ChatMessage usage in workflow files (use text= instead of contents= for strings) - Fix AgentResponse.from_updates -> from_agent_run_response_updates in workflow files - Fix test files for ChatMessage and Role enum usage * Fix remaining ChatMessage API usage in test files * Fix more ChatMessage and Role API changes in source and test files - Fix ChatMessage in _magentic.py replan method - Fix Role enum comparison in test assertions - Fix remaining test files with old ChatMessage syntax * Fix ChatMessage and Role API changes across packages - Add Role import where missing - Fix ChatMessage signature: positional args to keyword args (role=, text=, contents=) - Fix Role enum comparisons: .role.value instead of .role string - Fix FinishReason enum usage in ag-ui event converters - Rename AgentResponse.from_updates to from_agent_run_response_updates in ag-ui Fixes API compatibility after Types API Review improvements merge * Fix ChatMessage and Role API changes in github_copilot tests * Fix ChatMessage and Role API changes in redis and github_copilot packages - Fix redis provider: Role enum comparison using .value - Fix redis tests: ChatMessage signature and Role comparisons - Fix github_copilot tests: ChatMessage signature and Role comparisons - Update docstring examples in redis chat message store * Fix ChatMessage and Role API changes in devui package - Fix executor: ChatMessage signature change - Fix conversations: Role enum to string conversion in two places - Fix tests: ChatMessage signatures and Role comparisons * Fix ChatMessage and Role API changes in a2a and lab packages - Fix a2a tests: Role comparisons and ChatMessage signatures - Fix lab tau2 source: Role enum comparison in flip_messages, log_messages, sliding_window - Fix lab tau2 tests: ChatMessage signatures and Role comparisons * Remove duplicate test files from ag-ui/tests (tests are in ag_ui_tests) * Fix ChatMessage and Role API changes across packages After rebasing on upstream/main which merged PR #3647 (Types API Review improvements), fix all packages to use the new API: - ChatMessage: Use keyword args (role=, text=, contents=) instead of positional args - Role: Compare using .value attribute since it's now an enum Packages fixed: - ag-ui: Fixed Role value extraction bugs in _message_adapters.py - anthropic: Fixed ChatMessage and Role comparisons in tests - azure-ai: Fixed Role comparison in _client.py - azure-ai-search: Fixed ChatMessage and Role in source/tests - bedrock: Fixed ChatMessage signatures in tests - chatkit: Fixed ChatMessage and Role in source/tests - copilotstudio: Fixed ChatMessage and Role in tests - declarative: Fixed ChatMessage in _executors_agents.py - mem0: Fixed ChatMessage and Role in source/tests - purview: Fixed ChatMessage in source/tests * Fix mypy errors for ChatMessage and Role API changes - durabletask: Use str() fallback in role value extraction - core: Fix ChatMessage in _orchestrator_helpers.py to use keyword args - core: Add type ignore for _conversation_state.py contents deserialization - ag-ui: Fix type ignore comments (call-overload instead of arg-type) - azure-ai-search: Fix get_role_value type hint to accept Any - lab: Move get_role_value to module level with Any type hint * Improve CI test timeout configuration - Increase job timeout from 10 to 15 minutes - Reduce per-test timeout to 60s (was 900s/300s) - Add --timeout_method thread for better timeout handling - Add --timeout-verbose to see which tests are slow - Reduce retries from 3 to 2 and delay from 10s to 5s This ensures individual test timeouts are shorter than the job timeout, providing better visibility when tests hang. With 60s timeout and 2 retries, worst case per test is ~180s. * Fix ChatMessage API usage in docstrings and source - Fix ChatMessage positional args in docstrings: _serialization.py, _threads.py, _middleware.py - Fix ChatMessage in tau2 runner.py - Fix role comparison in _orchestrator_helpers.py to use .value - Fix role comparison in _group_chat.py docstring example - Fix role assertions in test_durable_entities.py to use .value * Revert tool_choice/parallel_tool_calls changes - must be removed when no tools OpenAI API requires tool_choice and parallel_tool_calls to only be present when tools are specified. Restored the logic that removes these options when there are no tools. - Restored check in _chat_client.py to remove tool_choice and parallel_tool_calls when no tools present - Restored same logic in _responses_client.py - Reverted test to expect the correct behavior * fixed issue in tests * fix: resolve merge conflict markers in ag-ui tests * fix: restructure ag-ui tests and fix Role/FinishReason to use string types * fix: streaming function invocation and middleware termination - Refactor streaming function invocation to use get_final_response() on inner streams - Fix MiddlewareTermination to accept result parameter for passing results - Fix _AutoHandoffMiddleware to use MiddlewareTermination instead of context.terminate - Fix AgentMiddlewareLayer.run() to properly forward function/chat middleware - Remove duplicate middleware registration in AgentMiddlewareLayer.__init__ - Fix exception handling in _auto_invoke_function to properly capture termination - Fix mypy errors in core package - Update tests to use stream=True parameter for unified run API * fix all tests command * Refactor integration tests to use pytest fixtures - Merge testutils.py into conftest.py for azurefunctions integration tests - Merge dt_testutils.py into conftest.py for durabletask integration tests - Convert all integration tests to use fixtures instead of direct imports (fixes ModuleNotFoundError with --import-mode=importlib) - Add sample_helper fixture for azurefunctions tests - Add agent_client_factory and orchestration_helper fixtures for durabletask - Integration tests now skip with descriptive messages when services unavailable - Restructure devui tests into tests/devui/ with proper conftest.py - Add test organization guidelines to CODING_STANDARD.md - Remove __init__.py from test directories per pytest best practices * Fix pytest_collection_modifyitems to only skip integration tests The hook was skipping all tests in the test session, not just integration tests. Now it only skips items in the integration_tests directory. * Fix mem0 tests failing on Python 3.13 Use patch.object on the imported module instead of @patch with string path to ensure the mock takes effect regardless of import timing. * fix mem0 * another attempt for mem0 * fix for mem0 * fix mem0 * Increase worker initialization wait time in durabletask tests Increase from 2 to 8 seconds to allow time for: - Python startup and module imports - Azure OpenAI client creation - Agent registration with DTS worker - Worker connection to DTS This helps prevent test failures in CI where the first tests may run before the worker is fully ready to process requests. * Fix streaming test to use ResponseStream with finalizer The _consume_stream method now expects a ResponseStream that can provide a final AgentResponse via get_final_response(). Update the test to use ResponseStream with AgentResponse.from_updates as the finalizer. * Fix MockToolCallingAgent to use new ResponseStream API and update samples * small updates to run_stream to run * fix sub workflow * temp fix for az func test --------- Co-authored-by: Dmytro Struk <13853051+dmytrostruk@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2026-02-05 21:09:58 +01:00
parent d1205896a1
commit 3dc59c83b5
372 changed files with 11583 additions and 9465 deletions
@@ -0,0 +1,755 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for message mapping functionality.
+
+This module tests the MessageMapper which converts Agent Framework events
+to OpenAI-compatible streaming events. Tests use REAL classes from
+agent_framework, not mocks, to ensure proper serialization.
+"""
+
+from typing import Any
+
+import pytest
+
+# Import Agent Framework types
+from agent_framework._types import (
+    AgentResponseUpdate,
+    Content,
+)
+
+# Import real workflow event classes - NOT mocks!
+from agent_framework._workflows._events import (
+    ExecutorCompletedEvent,
+    WorkflowStartedEvent,
+    WorkflowStatusEvent,
+)
+
+# Import factory functions from conftest for parameterized test data creation
+from conftest import (
+    create_agent_run_response,
+    create_executor_completed_event,
+    create_executor_failed_event,
+    create_executor_invoked_event,
+)
+
+from agent_framework_devui._mapper import MessageMapper
+from agent_framework_devui.models._openai_custom import (
+    AgentCompletedEvent,
+    AgentFailedEvent,
+    AgentFrameworkRequest,
+    AgentStartedEvent,
+)
+
+# Note: mapper and test_request fixtures are provided by conftest.py
+
+
+# =============================================================================
+# Test Helpers
+# =============================================================================
+
+
+def create_test_content(content_type: str, **kwargs: Any) -> Any:
+    """Create test content objects."""
+    if content_type == "text":
+        return Content.from_text(text=kwargs.get("text", "Hello, world!"))
+    if content_type == "function_call":
+        return Content.from_function_call(
+            call_id=kwargs.get("call_id", "test_call_id"),
+            name=kwargs.get("name", "test_func"),
+            arguments=kwargs.get("arguments", {"param": "value"}),
+        )
+    if content_type == "error":
+        return Content.from_error(
+            message=kwargs.get("message", "Test error"), error_code=kwargs.get("code", "test_error")
+        )
+    raise ValueError(f"Unknown content type: {content_type}")
+
+
+def create_test_agent_update(contents: list[Any]) -> AgentResponseUpdate:
+    """Create test AgentResponseUpdate."""
+    return AgentResponseUpdate(contents=contents, role="assistant", message_id="test_msg", response_id="test_resp")
+
+
+# =============================================================================
+# Basic Content Mapping Tests
+# =============================================================================
+
+
+async def test_critical_isinstance_bug_detection(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """CRITICAL: Test that would have caught the isinstance vs hasattr bug."""
+    content = create_test_content("text", text="Bug detection test")
+    update = create_test_agent_update([content])
+
+    # Key assertions that would have caught the bug
+    assert hasattr(update, "contents")  # Real attribute
+    assert not hasattr(update, "response")  # Fake attribute should not exist
+
+    # Test isinstance works with real types
+    assert isinstance(update, AgentResponseUpdate)
+
+    # Test mapper conversion - should NOT produce "Unknown event"
+    events = await mapper.convert_event(update, test_request)
+
+    assert len(events) > 0
+    assert all(hasattr(event, "type") for event in events)
+    assert all(event.type != "unknown" for event in events)
+
+
+async def test_text_content_mapping(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test TextContent mapping with proper OpenAI event hierarchy."""
+    content = create_test_content("text", text="Hello, clean test!")
+    update = create_test_agent_update([content])
+
+    events = await mapper.convert_event(update, test_request)
+
+    # With proper OpenAI hierarchy, we expect 3 events:
+    # 1. response.output_item.added (message)
+    # 2. response.content_part.added (text part)
+    # 3. response.output_text.delta (actual text)
+    assert len(events) == 3
+
+    # Check message output item
+    assert events[0].type == "response.output_item.added"
+    assert events[0].item.type == "message"
+    assert events[0].item.role == "assistant"
+
+    # Check content part
+    assert events[1].type == "response.content_part.added"
+    assert events[1].part.type == "output_text"
+
+    # Check text delta
+    assert events[2].type == "response.output_text.delta"
+    assert events[2].delta == "Hello, clean test!"
+
+
+async def test_function_call_mapping(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test FunctionCallContent mapping."""
+    content = create_test_content("function_call", name="test_func", arguments={"location": "TestCity"})
+    update = create_test_agent_update([content])
+
+    events = await mapper.convert_event(update, test_request)
+
+    # Should generate: response.output_item.added + response.function_call_arguments.delta
+    assert len(events) >= 2
+    assert events[0].type == "response.output_item.added"
+    assert events[1].type == "response.function_call_arguments.delta"
+
+    # Check JSON is in delta event
+    delta_events = [e for e in events if e.type == "response.function_call_arguments.delta"]
+    full_json = "".join(event.delta for event in delta_events)
+    assert "TestCity" in full_json
+
+
+async def test_function_result_content_with_string_result(
+    mapper: MessageMapper, test_request: AgentFrameworkRequest
+) -> None:
+    """Test FunctionResultContent with plain string result (regular tools)."""
+    content = Content.from_function_result(
+        call_id="test_call_123",
+        result="Hello, World!",
+    )
+    update = create_test_agent_update([content])
+
+    events = await mapper.convert_event(update, test_request)
+
+    assert len(events) >= 1
+    result_events = [e for e in events if e.type == "response.function_result.complete"]
+    assert len(result_events) == 1
+    assert result_events[0].output == "Hello, World!"
+    assert result_events[0].call_id == "test_call_123"
+    assert result_events[0].status == "completed"
+
+
+async def test_function_result_content_with_nested_content_objects(
+    mapper: MessageMapper, test_request: AgentFrameworkRequest
+) -> None:
+    """Test FunctionResultContent with nested Content objects (MCP tools case)."""
+    content = Content.from_function_result(
+        call_id="mcp_call_456",
+        result=[Content.from_text(text="Hello from MCP!")],
+    )
+    update = create_test_agent_update([content])
+
+    events = await mapper.convert_event(update, test_request)
+
+    assert len(events) >= 1
+    result_events = [e for e in events if e.type == "response.function_result.complete"]
+    assert len(result_events) == 1
+    assert "Hello from MCP!" in result_events[0].output
+    assert result_events[0].call_id == "mcp_call_456"
+
+
+async def test_error_content_mapping(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test ErrorContent mapping."""
+    content = create_test_content("error", message="Test error", code="test_code")
+    update = create_test_agent_update([content])
+
+    events = await mapper.convert_event(update, test_request)
+
+    assert len(events) == 1
+    assert events[0].type == "error"
+    assert events[0].message == "Test error"
+    assert events[0].code == "test_code"
+
+
+async def test_mixed_content_types(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test multiple content types together."""
+    contents = [
+        create_test_content("text", text="Starting..."),
+        create_test_content("function_call", name="process", arguments={"data": "test"}),
+        create_test_content("text", text="Done!"),
+    ]
+    update = create_test_agent_update(contents)
+
+    events = await mapper.convert_event(update, test_request)
+
+    assert len(events) >= 3
+    event_types = {event.type for event in events}
+    assert "response.output_text.delta" in event_types
+    assert "response.function_call_arguments.delta" in event_types
+
+
+# =============================================================================
+# Agent Lifecycle Event Tests
+# =============================================================================
+
+
+async def test_agent_lifecycle_events(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test that agent lifecycle events are properly converted to OpenAI format."""
+    # Test AgentStartedEvent
+    start_event = AgentStartedEvent()
+    events = await mapper.convert_event(start_event, test_request)
+
+    assert len(events) == 2  # response.created and response.in_progress
+    assert events[0].type == "response.created"
+    assert events[1].type == "response.in_progress"
+    assert events[0].response.model == "devui"
+    assert events[0].response.status == "in_progress"
+
+    # Test AgentCompletedEvent
+    complete_event = AgentCompletedEvent()
+    events = await mapper.convert_event(complete_event, test_request)
+    # AgentCompletedEvent no longer emits response.completed to avoid duplicates
+    assert len(events) == 0
+
+    # Test AgentFailedEvent
+    error = Exception("Test error")
+    failed_event = AgentFailedEvent(error=error)
+    events = await mapper.convert_event(failed_event, test_request)
+
+    assert len(events) == 1
+    assert events[0].type == "response.failed"
+    assert events[0].response.status == "failed"
+    assert events[0].response.error.message == "Test error"
+
+
+async def test_agent_run_response_mapping(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test that mapper handles complete AgentResponse (non-streaming)."""
+    response = create_agent_run_response("Complete response from run()")
+
+    events = await mapper.convert_event(response, test_request)
+
+    assert len(events) > 0
+    text_events = [e for e in events if e.type == "response.output_text.delta"]
+    assert len(text_events) > 0
+    assert text_events[0].delta == "Complete response from run()"
+
+
+# =============================================================================
+# Workflow Executor Event Tests (using REAL classes, not mocks!)
+# =============================================================================
+
+
+async def test_executor_invoked_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test ExecutorInvokedEvent using the REAL class from agent_framework."""
+    # Use real class, not mock!
+    event = create_executor_invoked_event(executor_id="exec_123")
+
+    events = await mapper.convert_event(event, test_request)
+
+    assert len(events) == 1
+    assert events[0].type == "response.output_item.added"
+    # Access as dict since item might be ExecutorActionItem
+    item = events[0].item if isinstance(events[0].item, dict) else events[0].item.model_dump()
+    assert item["type"] == "executor_action"
+    assert item["executor_id"] == "exec_123"
+    assert item["status"] == "in_progress"
+
+
+async def test_executor_completed_event_simple_data(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test ExecutorCompletedEvent with simple dict data."""
+    # Create event with simple data
+    event = ExecutorCompletedEvent(executor_id="exec_123", data={"simple": "result"})
+
+    # First need to invoke the executor to set up context
+    invoke_event = create_executor_invoked_event(executor_id="exec_123")
+    await mapper.convert_event(invoke_event, test_request)
+
+    # Now complete it
+    events = await mapper.convert_event(event, test_request)
+
+    assert len(events) == 1
+    assert events[0].type == "response.output_item.done"
+    item = events[0].item if isinstance(events[0].item, dict) else events[0].item.model_dump()
+    assert item["type"] == "executor_action"
+    assert item["executor_id"] == "exec_123"
+    assert item["status"] == "completed"
+    # Result should be serialized
+    assert item["result"] == {"simple": "result"}
+
+
+async def test_executor_completed_event_with_agent_response(
+    mapper: MessageMapper, test_request: AgentFrameworkRequest
+) -> None:
+    """Test ExecutorCompletedEvent with nested AgentExecutorResponse.
+
+    This is a REGRESSION TEST for the serialization bug where
+    ExecutorCompletedEvent.data contained AgentExecutorResponse with nested
+    AgentResponse and ChatMessage objects (SerializationMixin) that
+    Pydantic couldn't serialize.
+    """
+    # Create event with realistic nested data - the exact structure that caused the bug
+    event = create_executor_completed_event(executor_id="exec_agent", with_agent_response=True)
+
+    # Verify the data has the problematic structure
+    assert hasattr(event.data, "agent_response")
+    assert hasattr(event.data, "full_conversation")
+
+    # First invoke the executor
+    invoke_event = create_executor_invoked_event(executor_id="exec_agent")
+    await mapper.convert_event(invoke_event, test_request)
+
+    # Now complete - this should NOT raise serialization errors
+    events = await mapper.convert_event(event, test_request)
+
+    assert len(events) == 1
+    assert events[0].type == "response.output_item.done"
+
+    # Get the item (might be Pydantic model or dict)
+    item = events[0].item if isinstance(events[0].item, dict) else events[0].item.model_dump()
+    assert item["type"] == "executor_action"
+    assert item["executor_id"] == "exec_agent"
+    assert item["status"] == "completed"
+
+    # The result should be serialized (converted to dict)
+    result = item["result"]
+    assert result is not None
+    # Should be a dict or list, not the original object
+    assert isinstance(result, (dict, list))
+
+
+async def test_executor_completed_event_serialization_to_json(
+    mapper: MessageMapper, test_request: AgentFrameworkRequest
+) -> None:
+    """REGRESSION TEST: Verify the full JSON serialization works.
+
+    This tests the exact failure mode from the bug: calling model_dump_json()
+    on the event containing nested SerializationMixin objects.
+    """
+    # Create the problematic event
+    event = create_executor_completed_event(executor_id="exec_json_test", with_agent_response=True)
+
+    # Invoke first
+    invoke_event = create_executor_invoked_event(executor_id="exec_json_test")
+    await mapper.convert_event(invoke_event, test_request)
+
+    # Complete
+    events = await mapper.convert_event(event, test_request)
+
+    assert len(events) == 1
+    done_event = events[0]
+
+    # This is the critical test - model_dump_json() should NOT raise
+    # "Unable to serialize unknown type: <class 'agent_framework._types.AgentResponse'>"
+    try:
+        json_str = done_event.model_dump_json()
+        assert json_str is not None
+        assert len(json_str) > 0
+        # Verify it's valid JSON by checking it contains expected fields
+        assert "executor_action" in json_str
+        assert "exec_json_test" in json_str
+        assert "completed" in json_str
+    except Exception as e:
+        pytest.fail(f"model_dump_json() raised an exception: {e}")
+
+
+async def test_executor_failed_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test ExecutorFailedEvent using the REAL class."""
+    # First invoke the executor
+    invoke_event = create_executor_invoked_event(executor_id="exec_fail")
+    await mapper.convert_event(invoke_event, test_request)
+
+    # Now fail it
+    event = create_executor_failed_event(executor_id="exec_fail", error_message="Executor failed")
+    events = await mapper.convert_event(event, test_request)
+
+    assert len(events) == 1
+    assert events[0].type == "response.output_item.done"
+    item = events[0].item if isinstance(events[0].item, dict) else events[0].item.model_dump()
+    assert item["type"] == "executor_action"
+    assert item["executor_id"] == "exec_fail"
+    assert item["status"] == "failed"
+    assert "Executor failed" in str(item["error"])
+
+
+# =============================================================================
+# Workflow Lifecycle Event Tests
+# =============================================================================
+
+
+async def test_workflow_started_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test WorkflowStartedEvent using the REAL class."""
+
+    event = WorkflowStartedEvent(data=None)
+    events = await mapper.convert_event(event, test_request)
+
+    # WorkflowStartedEvent should emit response.created and response.in_progress
+    assert len(events) == 2
+    assert events[0].type == "response.created"
+    assert events[1].type == "response.in_progress"
+
+
+async def test_workflow_status_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test WorkflowStatusEvent using the REAL class."""
+    from agent_framework._workflows._events import WorkflowRunState
+
+    event = WorkflowStatusEvent(state=WorkflowRunState.IN_PROGRESS)
+    events = await mapper.convert_event(event, test_request)
+
+    # Should emit some status-related event
+    assert len(events) >= 0  # May emit events or may be filtered
+
+
+# =============================================================================
+# Magentic Event Tests - Testing WorkflowOutputEvent with additional_properties
+# =============================================================================
+
+
+async def test_magentic_agent_run_update_event_with_agent_delta_metadata(
+    mapper: MessageMapper, test_request: AgentFrameworkRequest
+) -> None:
+    """Test that WorkflowOutputEvent with magentic_event_type='agent_delta' is handled correctly.
+
+    This tests the ACTUAL event format Magentic emits - not a fake MagenticAgentDeltaEvent class.
+    Magentic uses WorkflowOutputEvent wrapping AgentResponseUpdate with additional_properties.
+    """
+    from agent_framework._types import AgentResponseUpdate
+    from agent_framework._workflows._events import WorkflowOutputEvent
+
+    # Create the REAL event format that Magentic emits
+    update = AgentResponseUpdate(
+        contents=[Content.from_text(text="Hello from agent")],
+        role="assistant",
+        author_name="Writer",
+        additional_properties={
+            "magentic_event_type": "agent_delta",
+            "agent_id": "writer_agent",
+        },
+    )
+    event = WorkflowOutputEvent(executor_id="magentic_executor", data=update)
+
+    events = await mapper.convert_event(event, test_request)
+
+    # Should be treated as a regular WorkflowOutputEvent with text content
+    # The mapper should emit text delta events
+    assert len(events) >= 1
+    text_events = [e for e in events if getattr(e, "type", "") == "response.output_text.delta"]
+    assert len(text_events) >= 1
+    assert text_events[0].delta == "Hello from agent"
+
+
+async def test_magentic_orchestrator_message_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test that WorkflowOutputEvent with magentic_event_type='orchestrator_message' is handled.
+
+    Magentic emits orchestrator planning/instruction messages using WorkflowOutputEvent
+    wrapping AgentResponseUpdate with additional_properties.
+    """
+    from agent_framework._types import AgentResponseUpdate
+    from agent_framework._workflows._events import WorkflowOutputEvent
+
+    # Create orchestrator message event (REAL format from Magentic)
+    update = AgentResponseUpdate(
+        contents=[Content.from_text(text="Planning: First, the writer will create content...")],
+        role="assistant",
+        author_name="Orchestrator",
+        additional_properties={
+            "magentic_event_type": "orchestrator_message",
+            "orchestrator_message_kind": "task_ledger",
+            "orchestrator_id": "magentic_orchestrator",
+        },
+    )
+    event = WorkflowOutputEvent(executor_id="magentic_orchestrator", data=update)
+
+    events = await mapper.convert_event(event, test_request)
+
+    # Currently, mapper treats this as regular WorkflowOutputEvent (no special handling)
+    # This test documents the current behavior
+    assert len(events) >= 1
+    text_events = [e for e in events if getattr(e, "type", "") == "response.output_text.delta"]
+    assert len(text_events) >= 1
+    assert "Planning:" in text_events[0].delta
+
+
+async def test_magentic_events_use_same_event_class_as_other_workflows(
+    mapper: MessageMapper, test_request: AgentFrameworkRequest
+) -> None:
+    """Verify Magentic uses the same WorkflowOutputEvent class as other workflows.
+
+    This test documents that Magentic does NOT define separate event classes like
+    MagenticAgentDeltaEvent - it reuses WorkflowOutputEvent with metadata in
+    additional_properties. Any mapper code checking for 'MagenticAgentDeltaEvent'
+    class names is dead code.
+    """
+    from agent_framework._types import AgentResponseUpdate
+    from agent_framework._workflows._events import WorkflowOutputEvent
+
+    # Create events the way different workflows do it
+    # 1. Regular workflow (no additional_properties)
+    regular_update = AgentResponseUpdate(
+        contents=[Content.from_text(text="Regular workflow response")],
+        role="assistant",
+    )
+    regular_event = WorkflowOutputEvent(executor_id="regular_executor", data=regular_update)
+
+    # 2. Magentic workflow (with additional_properties)
+    magentic_update = AgentResponseUpdate(
+        contents=[Content.from_text(text="Magentic workflow response")],
+        role="assistant",
+        additional_properties={"magentic_event_type": "agent_delta"},
+    )
+    magentic_event = WorkflowOutputEvent(executor_id="magentic_executor", data=magentic_update)
+
+    # Both should be the SAME class
+    assert type(regular_event) is type(magentic_event)
+    assert isinstance(regular_event, WorkflowOutputEvent)
+    assert isinstance(magentic_event, WorkflowOutputEvent)
+
+    # Both should be handled by the same isinstance check in mapper
+    regular_events = await mapper.convert_event(regular_event, test_request)
+    magentic_events = await mapper.convert_event(magentic_event, test_request)
+
+    # Both produce text delta events
+    regular_text = [e for e in regular_events if getattr(e, "type", "") == "response.output_text.delta"]
+    magentic_text = [e for e in magentic_events if getattr(e, "type", "") == "response.output_text.delta"]
+
+    assert len(regular_text) >= 1
+    assert len(magentic_text) >= 1
+
+
+# =============================================================================
+# Unknown Content Fallback Tests
+# =============================================================================
+
+
+async def test_unknown_content_fallback(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test graceful handling of unknown content types."""
+
+    class MockUnknownContent:
+        def __init__(self):
+            self.__class__.__name__ = "WeirdUnknownContent"
+
+    context = mapper._get_or_create_context(test_request)
+    unknown_content = MockUnknownContent()
+
+    event = await mapper._create_unknown_content_event(unknown_content, context)
+
+    assert event.type == "response.output_text.delta"
+    assert "Unknown content type" in event.delta
+    assert "WeirdUnknownContent" in event.delta
+
+
+# =============================================================================
+# WorkflowOutputEvent Tests
+# =============================================================================
+
+
+async def test_workflow_output_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test WorkflowOutputEvent is converted to output_item.added."""
+    from agent_framework._workflows._events import WorkflowOutputEvent
+
+    event = WorkflowOutputEvent(data="Final workflow output", executor_id="final_executor")
+    events = await mapper.convert_event(event, test_request)
+
+    # WorkflowOutputEvent should emit output_item.added
+    assert len(events) == 1
+    assert events[0].type == "response.output_item.added"
+    # Check item contains the output text
+    item = events[0].item
+    assert item.type == "message"
+    assert any("Final workflow output" in str(c) for c in item.content)
+
+
+async def test_workflow_output_event_with_list_data(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test WorkflowOutputEvent with list data (common for sequential/concurrent workflows)."""
+    from agent_framework import ChatMessage
+    from agent_framework._workflows._events import WorkflowOutputEvent
+
+    # Sequential/Concurrent workflows often output list[ChatMessage]
+    messages = [
+        ChatMessage(role="user", contents=[Content.from_text(text="Hello")]),
+        ChatMessage(role="assistant", contents=[Content.from_text(text="World")]),
+    ]
+    event = WorkflowOutputEvent(data=messages, executor_id="complete")
+    events = await mapper.convert_event(event, test_request)
+
+    assert len(events) == 1
+    assert events[0].type == "response.output_item.added"
+
+
+# =============================================================================
+# WorkflowFailedEvent Tests
+# =============================================================================
+
+
+async def test_workflow_failed_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test WorkflowFailedEvent is converted to response.failed."""
+    from agent_framework._workflows._events import WorkflowErrorDetails, WorkflowFailedEvent
+
+    details = WorkflowErrorDetails(
+        error_type="TestError",
+        message="Workflow failed due to test error",
+        executor_id="failing_executor",
+    )
+    event = WorkflowFailedEvent(details=details)
+    events = await mapper.convert_event(event, test_request)
+
+    # WorkflowFailedEvent should emit response.failed
+    assert len(events) >= 1
+    # Find the failed event
+    failed_events = [e for e in events if getattr(e, "type", "") == "response.failed"]
+    assert len(failed_events) == 1, f"Expected response.failed, got types: {[getattr(e, 'type', '') for e in events]}"
+    # Check response contains error info
+    response = failed_events[0].response
+    assert response.status == "failed"
+    assert response.error is not None
+    # Verify error message is correctly extracted from details.message (not "Unknown error")
+    assert "Workflow failed due to test error" in response.error.message
+    assert "Unknown error" not in response.error.message
+
+
+async def test_workflow_failed_event_with_extra(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test WorkflowFailedEvent includes extra context when available."""
+    from agent_framework._workflows._events import WorkflowErrorDetails, WorkflowFailedEvent
+
+    details = WorkflowErrorDetails(
+        error_type="ValidationError",
+        message="Input validation failed",
+        executor_id="validation_executor",
+        extra={"field": "email", "reason": "invalid format"},
+    )
+    event = WorkflowFailedEvent(details=details)
+    events = await mapper.convert_event(event, test_request)
+
+    assert len(events) == 1
+    assert events[0].type == "response.failed"
+    response = events[0].response
+    # Verify both the message and extra context are included
+    assert "Input validation failed" in response.error.message
+    assert "extra:" in response.error.message
+    assert "email" in response.error.message
+
+
+async def test_workflow_failed_event_with_traceback(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test WorkflowFailedEvent includes traceback when available."""
+    from agent_framework._workflows._events import WorkflowErrorDetails, WorkflowFailedEvent
+
+    details = WorkflowErrorDetails(
+        error_type="ValueError",
+        message="Invalid input provided",
+        traceback="Traceback (most recent call last):\n  File ...\nValueError: Invalid input",
+        executor_id="validation_executor",
+    )
+    event = WorkflowFailedEvent(details=details)
+    events = await mapper.convert_event(event, test_request)
+
+    assert len(events) == 1
+    assert events[0].type == "response.failed"
+
+
+# =============================================================================
+# WorkflowWarningEvent and WorkflowErrorEvent Tests
+# =============================================================================
+
+
+async def test_workflow_warning_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test WorkflowWarningEvent is converted to trace event."""
+    from agent_framework._workflows._events import WorkflowWarningEvent
+
+    event = WorkflowWarningEvent(data="This is a warning message")
+    events = await mapper.convert_event(event, test_request)
+
+    # WorkflowWarningEvent should emit a trace event
+    assert len(events) == 1
+    assert events[0].type == "response.trace.completed"
+    assert events[0].data["event_type"] == "WorkflowWarningEvent"
+
+
+async def test_workflow_error_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test WorkflowErrorEvent is converted to trace event."""
+    from agent_framework._workflows._events import WorkflowErrorEvent
+
+    event = WorkflowErrorEvent(data=ValueError("Something went wrong"))
+    events = await mapper.convert_event(event, test_request)
+
+    # WorkflowErrorEvent should emit a trace event
+    assert len(events) == 1
+    assert events[0].type == "response.trace.completed"
+    assert events[0].data["event_type"] == "WorkflowErrorEvent"
+
+
+# =============================================================================
+# RequestInfoEvent Tests (Human-in-the-Loop)
+# =============================================================================
+
+
+async def test_request_info_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test RequestInfoEvent is converted to HIL request event."""
+    from agent_framework._workflows._events import RequestInfoEvent
+
+    event = RequestInfoEvent(
+        request_id="req_123",
+        source_executor_id="approval_executor",
+        request_data={"action": "approve", "details": "Please approve this action"},
+        response_type=str,
+    )
+    events = await mapper.convert_event(event, test_request)
+
+    # RequestInfoEvent should emit response.request_info.requested
+    assert len(events) >= 1
+    # Check that request info is captured
+    has_hil_event = any(getattr(e, "type", "") == "response.request_info.requested" for e in events)
+    assert has_hil_event, f"Expected response.request_info.requested, got: {[getattr(e, 'type', '') for e in events]}"
+
+    # Verify the event contains the expected data
+    hil_event = [e for e in events if getattr(e, "type", "") == "response.request_info.requested"][0]
+    assert hil_event.request_id == "req_123"
+    assert hil_event.source_executor_id == "approval_executor"
+
+
+# =============================================================================
+# SuperStep Event Tests
+# =============================================================================
+
+
+async def test_superstep_started_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test SuperStepStartedEvent is handled gracefully."""
+    from agent_framework._workflows._events import SuperStepStartedEvent
+
+    event = SuperStepStartedEvent(iteration=1)
+    events = await mapper.convert_event(event, test_request)
+
+    # SuperStepStartedEvent may not emit events (internal workflow signal)
+    # Just ensure it doesn't crash
+    assert isinstance(events, list)
+
+
+async def test_superstep_completed_event(mapper: MessageMapper, test_request: AgentFrameworkRequest) -> None:
+    """Test SuperStepCompletedEvent is handled gracefully."""
+    from agent_framework._workflows._events import SuperStepCompletedEvent
+
+    event = SuperStepCompletedEvent(iteration=1)
+    events = await mapper.convert_event(event, test_request)
+
+    # SuperStepCompletedEvent may not emit events (internal workflow signal)
+    # Just ensure it doesn't crash
+    assert isinstance(events, list)