microsoft/semantic-kernel · error · AgentInitializationException

response_format must be a dictionary, a subclass of BaseMode

Error message

response_format must be a dictionary, a subclass of BaseModel, a Python class/type, or None

What it means

Raised by configure_response_format() when response_format is none of the accepted kinds: it is not None/'auto', not a dict, not a type/class. This is the final else branch — the value's top-level type is entirely unrecognized.

Source

Thrown at python/semantic_kernel/agents/open_ai/openai_responses_agent.py:809

                configured_format = {
                    "type": "json_schema",
                    "name": interim_format.get("name", response_format.__name__),
                    "schema": interim_format.get("schema"),
                    "strict": interim_format.get("strict", True),
                }
            else:
                # Build a schema from a plain Python class
                generated_schema = KernelJsonSchemaBuilder.build(parameter_type=response_format, structured_output=True)
                if generated_schema is None:
                    raise AgentInitializationException(f"Could not generate schema for the type {response_format}.")
                configured_format = {
                    "type": "json_schema",
                    "name": response_format.__name__,
                    "schema": generated_schema,
                    "strict": True,
                }
        else:
            raise AgentInitializationException(
                "response_format must be a dictionary, a subclass of BaseModel, a Python class/type, or None"
            )

        return {"format": configured_format}

    # endregion

    # region Invocation Methods

    @trace_agent_get_response
    @override
    async def get_response(
        self,
        messages: str | ChatMessageContent | list[str | ChatMessageContent] | None = None,
        *,
        thread: AgentThread | None = None,
        arguments: KernelArguments | None = None,
        kernel: "Kernel | None" = None,

View on GitHub (pinned to c028a0c7dc)

Solutions

Pass None, a dict (with type 'json_object'/'json_schema'), a pydantic BaseModel subclass, or a plain Python class.
If you have a JSON string, json.loads() it into a dict first.
Pass the class itself (e.g. MyModel), not an instance (e.g. MyModel()).

Example fix

// before
cfg = OpenAIResponsesAgent.configure_response_format(MyModel())

// after
cfg = OpenAIResponsesAgent.configure_response_format(MyModel)

Defensive patterns

Strategy: type-guard

Validate before calling

from pydantic import BaseModel
valid = response_format is None or isinstance(response_format, dict) or isinstance(response_format, type)
assert valid, 'response_format must be None, a dict, a class, or a BaseModel subclass'

Type guard

from pydantic import BaseModel
def is_accepted_response_format(fmt) -> bool:
    if fmt is None:
        return True
    if isinstance(fmt, dict):
        return True
    if isinstance(fmt, type):
        return True
    return False

Try / catch

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    cfg = OpenAIResponsesAgent.configure_response_format(fmt)
except AgentInitializationException as e:
    if 'must be a dictionary' in str(e):
        cfg = None  # or coerce fmt to a dict/class
    raise

Prevention

Pass the class, not an instance, when using a model/type.
json.loads() any JSON string into a dict first.
Restrict response_format to None, dict, BaseModel subclass, or plain class.

When it happens

Trigger: Passing a response_format that is an instance/object (not a class), an int, a list, a tuple, or any other non-dict, non-type value. (Strings are partly handled: 'auto' returns None earlier, but other bare strings fall through to this branch.)

Common situations: Passing an already-instantiated object instead of the class, passing a JSON string (instead of a dict), or passing a random primitive. Also when a variable intended to hold a format is accidentally left as some other value.

Related errors

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