[DevUI] PydanticSerializationError when using GroupChat workflow - AgentResponse not serializable

[moti-malka]

Description

When exporting a GroupChat workflow for DevUI discovery, the DevUI server fails with a PydanticSerializationError because GroupChat events contain AgentResponse objects which Pydantic's model_dump_json() cannot serialize.

Steps to Reproduce

1. Create a file with a GroupChat workflow exported for DevUI discovery:

from agent_framework import ChatAgent, GroupChatBuilder
from agent_framework.azure import AzureOpenAIChatClient

def get_azure_chat_client():
    return AzureOpenAIChatClient(
        azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
        api_key=os.getenv("AZURE_OPENAI_API_KEY"),
        azure_deployment=os.getenv("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"),
        api_version="2025-01-01-preview",
    )

chat_client = get_azure_chat_client()

agent1 = ChatAgent(name="Agent1", instructions="...", chat_client=chat_client)
agent2 = ChatAgent(name="Agent2", instructions="...", chat_client=chat_client)

def create_workflow():
    return (
        GroupChatBuilder()
        .participants([agent1, agent2])
        .build()
    )

# Export for DevUI discovery
workflow = create_workflow()

2. Run DevUI: devui .

3. Open the DevUI in browser and try to use the workflow

Expected Behavior

GroupChat workflows should work in DevUI just like single ChatAgents.

Actual Behavior

DevUI returns HTTP 422 Unprocessable Content:

INFO:     127.0.0.1:56972 - "GET /v1/entities/example/info?type=workflow HTTP/1.1" 422 Unprocessable Content

The underlying error is:

PydanticSerializationError: Unable to serialize unknown type: <class 'agent_framework._types.AgentResponse'>

Root Cause Analysis

Looking at the codebase:

1. AgentResponse extends SerializationMixin and has to_dict()/to_json() methods
2. However, when Pydantic tries to serialize events from GroupChat using model_dump_json(), it doesn't know how to handle AgentResponse objects embedded in the events
3. The _mapper.py has _serialize_content_recursive() function, but it seems this isn't being applied in the DevUI serialization path

Workaround

Currently, the only workaround is to export a single ChatAgent instead of a GroupChat workflow for DevUI compatibility:

# Instead of exporting GroupChat workflow
agent = ChatAgent(name="MyAgent", instructions="...", chat_client=chat_client)

Environment

• agent-framework version: latest
• agent-framework-devui version: latest
• Python version: 3.13
• OS: macOS

Suggested Fix

Consider one of these approaches:

1. Add custom Pydantic serializers for AgentResponse and related types
2. Use the existing _serialize_content_recursive() logic in the DevUI serialization path
3. Register AgentResponse as a known Pydantic type with proper serialization

Related Code

• agent_framework/_types.py - AgentResponse class with SerializationMixin
• agent_framework/_mapper.py - _serialize_content_recursive() function
• test_execution.py - test_full_pipeline_agent_events_are_json_serializable test (shows this is a known concern)

[moti-malka]

✅ Solution Found

I found and tested a fix for this issue. The problem is in agent_framework_devui/_server.py in the _stream_execution method (around line 1110).

Root Cause

The serialization code checks if model_dump_json exists using hasattr(), but doesn't wrap the call in try/except. When model_dump_json() fails on nested unserializable types like AgentResponse, the exception propagates instead of falling back to alternative serialization methods (to_json(), to_dict(), etc.).

Current buggy code:

if hasattr(event, "model_dump_json"):
    payload = event.model_dump_json()  # Throws PydanticSerializationError!
elif hasattr(event, "to_json") and callable(getattr(event, "to_json", None)):
    # Never reached because model_dump_json exists but throws
    payload = event.to_json()

Proposed Fix

Wrap each serialization attempt in try/except to allow graceful fallback:

# IMPORTANT: Try model_dump_json FIRST because to_json() can have newlines (pretty-printing)
# which breaks SSE format. model_dump_json() returns single-line JSON.
# Wrap in try/except to handle nested unserializable types (e.g., AgentResponse)
payload = None
if hasattr(event, "model_dump_json"):
    try:
        payload = event.model_dump_json()
    except Exception:
        pass  # Fall through to alternative methods

if payload is None and hasattr(event, "to_json") and callable(getattr(event, "to_json", None)):
    try:
        payload = event.to_json()
        # Strip newlines from pretty-printed JSON for SSE compatibility
        payload = payload.replace("\n", "").replace("\r", "")
    except Exception:
        pass

if payload is None and hasattr(event, "to_dict") and callable(getattr(event, "to_dict", None)):
    try:
        payload = json.dumps(event.to_dict())
    except Exception:
        pass

if payload is None:
    if isinstance(event, dict):
        payload = json.dumps(event)
    else:
        payload = json.dumps(str(event))

Why This Works

AgentResponse inherits from SerializationMixin which provides to_json() and to_dict() methods that work correctly. By catching the PydanticSerializationError from model_dump_json() and falling back to these methods, the serialization succeeds.

Tested

I applied this patch locally and confirmed that GroupChat workflows now work correctly in DevUI without the serialization error.

Files to Modify

• agent_framework_devui/_server.py - _stream_execution method (~line 1110)

Happy to submit a PR if this approach looks good to the maintainers! 🚀