microsoft/semantic-kernel · error · ContentException

Session is required for SessionUpdateEvent

Error message

Session is required for SessionUpdateEvent

What it means

The OpenAI Realtime API's session.update event requires a 'session' object describing the session configuration (modalities, voice, turn detection, etc.). The _create_openai_realtime_client_event factory function raises ContentException if 'session' is not present in kwargs when event_type is SendEvents.SESSION_UPDATE.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/_open_ai_realtime.py:168

    SESSION_UPDATE = "session.update"
    INPUT_AUDIO_BUFFER_APPEND = "input_audio_buffer.append"
    INPUT_AUDIO_BUFFER_COMMIT = "input_audio_buffer.commit"
    INPUT_AUDIO_BUFFER_CLEAR = "input_audio_buffer.clear"
    CONVERSATION_ITEM_CREATE = "conversation.item.create"
    CONVERSATION_ITEM_TRUNCATE = "conversation.item.truncate"
    CONVERSATION_ITEM_DELETE = "conversation.item.delete"
    RESPONSE_CREATE = "response.create"
    RESPONSE_CANCEL = "response.cancel"


def _create_openai_realtime_client_event(event_type: SendEvents | str, **kwargs: Any) -> RealtimeClientEvent:
    """Create an OpenAI Realtime client event from a event type and kwargs."""
    if isinstance(event_type, str):
        event_type = SendEvents(event_type)
    match event_type:
        case SendEvents.SESSION_UPDATE:
            if "session" not in kwargs:
                raise ContentException("Session is required for SessionUpdateEvent")
            session_dict = kwargs.pop("session")
            # Create proper RealtimeSessionCreateRequest with required type field for SDK validation
            # The OpenAI SDK will handle the proper serialization for the API
            from openai.types.realtime import RealtimeSessionCreateRequest

            session_request = RealtimeSessionCreateRequest(type="realtime", **session_dict)
            return SessionUpdateEvent(
                type=event_type.value,
                session=session_request,
                **kwargs,
            )
        case SendEvents.INPUT_AUDIO_BUFFER_APPEND:
            if "audio" not in kwargs:
                raise ContentException("Audio is required for InputAudioBufferAppendEvent")
            return InputAudioBufferAppendEvent(
                type=event_type.value,
                **kwargs,
            )

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Always include a session dict when sending SESSION_UPDATE: send(event_type='session.update', session={'modalities': ['text'], 'voice': 'alloy'}).
2. Use the high-level update_session() method which constructs the session dict for you.
3. Validate kwargs presence before constructing the event.

Example fix

// before
await service.send(SendEvents.SESSION_UPDATE)
// after
await service.send(SendEvents.SESSION_UPDATE, session={'modalities': ['text', 'audio'], 'voice': 'alloy'})

def validate_session_update_kwargs(kwargs: dict) -> None:
    if 'session' not in kwargs:
        raise ValueError('SESSION_UPDATE event requires a session kwarg')
    if not isinstance(kwargs['session'], dict):
        raise TypeError(f'session must be a dict, got {type(kwargs["session"]).__name__}')

def has_valid_session_kwarg(kwargs: dict) -> bool:
    return 'session' in kwargs and isinstance(kwargs['session'], dict)

from semantic_kernel.exceptions import ContentException

try:
    event = _create_openai_realtime_client_event(SendEvents.SESSION_UPDATE, **kwargs)
except ContentException as e:
    kwargs['session'] = default_session_config
    event = _create_openai_realtime_client_event(SendEvents.SESSION_UPDATE, **kwargs)

When it happens

Trigger: Calling the realtime service's send/event API with SendEvents.SESSION_UPDATE (or the string 'session.update') without providing a session kwarg — e.g. service.send(RealtimeClientEvent('session.update')) with no session dict.

Common situations: Building events dynamically from user input or config where the session key was dropped; calling update_session() before session config is ready; misunderstanding the event API and thinking session is optional.

Related errors

• Audio is required for InputAudioBufferAppendEvent
• Audio track not initialized
• OpenAI WebRTC error: {error_text}
• Item is required for ConversationItemCreateEvent
• Item ID is required for ConversationItemDeleteEvent

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/30dd4b305519156f. Report an issue: GitHub.