microsoft/semantic-kernel · error · ContentException

Item is required for ConversationItemCreateEvent

Error message

Item is required for ConversationItemCreateEvent

What it means

The OpenAI Realtime API's conversation.item.create event requires an 'item' object describing the conversation item (message, function call, etc.). The event factory raises ContentException if 'item' is not in kwargs when event_type is SendEvents.CONVERSATION_ITEM_CREATE.

Source

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

            if "audio" not in kwargs:
                raise ContentException("Audio is required for InputAudioBufferAppendEvent")
            return InputAudioBufferAppendEvent(
                type=event_type.value,
                **kwargs,
            )
        case SendEvents.INPUT_AUDIO_BUFFER_COMMIT:
            return InputAudioBufferCommitEvent(
                type=event_type.value,
                **kwargs,
            )
        case SendEvents.INPUT_AUDIO_BUFFER_CLEAR:
            return InputAudioBufferClearEvent(
                type=event_type.value,
                **kwargs,
            )
        case SendEvents.CONVERSATION_ITEM_CREATE:
            if "item" not in kwargs:
                raise ContentException("Item is required for ConversationItemCreateEvent")
            kwargs["type"] = event_type.value
            return ConversationItemCreateEvent(**kwargs)
        case SendEvents.CONVERSATION_ITEM_TRUNCATE:
            if "content_index" not in kwargs:
                kwargs["content_index"] = 0
            return ConversationItemTruncateEvent(
                type=event_type.value,
                **kwargs,
            )
        case SendEvents.CONVERSATION_ITEM_DELETE:
            if "item_id" not in kwargs:
                raise ContentException("Item ID is required for ConversationItemDeleteEvent")
            return ConversationItemDeleteEvent(
                type=event_type.value,
                **kwargs,
            )
        case SendEvents.RESPONSE_CREATE:
            if "response" in kwargs:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Nest the conversation item properly: send(SendEvents.CONVERSATION_ITEM_CREATE, item={'type': 'message', 'role': 'user', 'content': [{'type': 'input_text', 'text': 'hello'}]}).
2. Use the SDK's helper or the high-level API if available to construct the item automatically.
3. Validate that 'item' key exists before calling send.

Example fix

// before
await service.send(SendEvents.CONVERSATION_ITEM_CREATE, type='message', role='user', content='hello')
// after
await service.send(SendEvents.CONVERSATION_ITEM_CREATE, item={'type': 'message', 'role': 'user', 'content': [{'type': 'input_text', 'text': 'hello'}]})

def validate_conversation_item_create_kwargs(kwargs: dict) -> None:
    if 'item' not in kwargs:
        raise ValueError('CONVERSATION_ITEM_CREATE requires an item kwarg')
    item = kwargs['item']
    if not isinstance(item, dict) or 'type' not in item:
        raise ValueError('item must be a dict with at least a type key')

def has_valid_item_kwarg(kwargs: dict) -> bool:
    return 'item' in kwargs and isinstance(kwargs['item'], dict) and 'type' in kwargs['item']

from semantic_kernel.exceptions import ContentException

try:
    await service.send(SendEvents.CONVERSATION_ITEM_CREATE, **kwargs)
except ContentException as e:
    if 'Item is required' in str(e):
        kwargs['item'] = {'type': 'message', 'role': 'user', 'content': [{'type': 'input_text', 'text': kwargs.pop('text', '')}]}
        await service.send(SendEvents.CONVERSATION_ITEM_CREATE, **kwargs)

When it happens

Trigger: Calling send(SendEvents.CONVERSATION_ITEM_CREATE) without an 'item' kwarg — e.g. providing the message content directly at the top level instead of nested under 'item'.

Common situations: Confusing the flat vs nested API shape — putting role/content at the kwargs root instead of inside an item dict; building the event from a partial payload that omitted item due to a conditional.

Related errors

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

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