Python: [Feature Request] Support custom WorkflowEvent emission for AG-UI/CopilotKit integration #3872

Problem Statement

MAF workflows cannot emit custom progress/activity events that surface through the AG-UI protocol. This blocks essential UX patterns for agentic applications like progress indicators, sub-task status, and activity notifications that frameworks like LangGraph support via their callback system.

Root Cause - Exact Code Location

File: agent_framework/_workflows/_agent.py
Method: WorkflowAgent._convert_workflow_event_to_agent_update()
Lines: 379-382

case _:
    # Ignore workflow-internal events  
    pass
return None

Hardcoded allowlist (Lines 306-378):

• AgentRunUpdateEvent (allowed)
• WorkflowOutputEvent (allowed)
• RequestInfoEvent (allowed)
• Everything else (filtered)

Impact

# Executors CAN emit custom events
await ctx.add_event(CustomProgressEvent(progress="Analyzing data..."))

# But WorkflowAgent filters them - never reaches AG-UI
# No error, no warning - silently dropped

Comparison to LangGraph

LangGraph (works):

await copilotkit_emit_state(config, {"search_progress": [...]})
# Emits STATE_SNAPSHOT event to AG-UI

MAF (blocked):

await ctx.add_event(ProgressEvent(data={...}))
# Filtered at WorkflowAgent layer, never reaches AG-UI

Proposed Solution

Add extensibility to _convert_workflow_event_to_agent_update():

Option 1: Custom event base class

case CustomAgentEvent(data=data, event_type=event_type):
    return AgentResponseUpdate(
        additional_properties={
            "custom_event_type": event_type,
            "custom_event_data": data
        }
    )

Option 2: Metadata flag

case event if getattr(event, 'surface_to_agent', False):
    # Pass through events marked for agent visibility
    return self._convert_custom_event(event)

Option 3: Event handler registry

# Allow registration of custom converters
WorkflowAgent.register_event_converter(MyCustomEvent, my_converter_func)

Use Cases

• Progress bars during long-running operations
• Sub-task completion tracking (like CopilotKit travel example)
• Activity indicators showing which agent is executing
• Custom status updates mid-execution

Workarounds Attempted

1. Emit via shared_state - not automatically propagated
2. Custom Executor subclass - events still filtered
3. Monkey-patch _convert_workflow_event_to_agent_update() - works but fragile

Context

Building AG-UI/CopilotKit frontend for MAF workflows. Need to emit ACTIVITY_SNAPSHOT events to show users which agent is currently executing and their progress, similar to how LangGraph integration works with copilotkit_emit_state/copilotkit_emit_message.