microsoft/semantic-kernel · error · AgentInitializationException

If response_format has type 'json_schema', 'json_schema' mus

Error message

If response_format has type 'json_schema', 'json_schema' must be a valid dictionary.

What it means

Raised by configure_response_format() when the response_format dict has type == 'json_schema' but its 'json_schema' value is not a dict. Structured Outputs require a schema object; a non-dict (string, list, None) would be sent to OpenAI and rejected, so the library validates the shape locally first.

Source

Thrown at python/semantic_kernel/agents/open_ai/openai_assistant_agent.py:669

        Args:
            response_format: The response format.

        Returns:
            AssistantResponseFormatOptionParam: The response format.
        """
        if response_format is None or response_format == "auto":
            return None

        configured_response_format = None
        if isinstance(response_format, dict):
            resp_type = response_format.get("type")
            if resp_type == "json_object":
                configured_response_format = {"type": "json_object"}
            elif resp_type == "json_schema":
                json_schema = response_format.get("json_schema")  # type: ignore
                if not isinstance(json_schema, dict):
                    raise AgentInitializationException(
                        "If response_format has type 'json_schema', 'json_schema' must be a valid dictionary."
                    )
                # We're assuming the response_format has already been provided in the correct format
                configured_response_format = response_format  # type: ignore
            else:
                raise AgentInitializationException(
                    f"Encountered unexpected response_format type: {resp_type}. Allowed types are `json_object` "
                    " and `json_schema`."
                )
        elif isinstance(response_format, type):
            # If it's a type, differentiate based on whether it's a BaseModel subclass
            if issubclass(response_format, BaseModel):
                configured_response_format = type_to_response_format_param(response_format)  # type: ignore
            else:
                generated_schema = KernelJsonSchemaBuilder.build(parameter_type=response_format, structured_output=True)
                assert generated_schema is not None  # nosec
                configured_response_format = generate_structured_output_response_format_schema(
                    name=response_format.__name__, schema=generated_schema

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass a full schema dict: {'type':'json_schema','json_schema':{'name':'...','schema':{...}}} matching OpenAI's structured output format.
2. If you have a BaseModel subclass, pass the class directly (not wrapped) so configure_response_format builds the schema via type_to_response_format_param.
3. Validate isinstance(response_format['json_schema'], dict) before calling.

Example fix

# before
response_format={'type':'json_schema','json_schema':'MyModel'}
fmt = OpenAIAssistantAgent.configure_response_format(response_format)

# after
response_format={'type':'json_schema','json_schema':{'name':'MyModel','schema':{'type':'object','properties':{...}}}}
fmt = OpenAIAssistantAgent.configure_response_format(response_format)

if isinstance(response_format, dict) and response_format.get('type') == 'json_schema':
    assert isinstance(response_format.get('json_schema'), dict), 'json_schema must be a dict'

def is_valid_json_schema_response_format(rf) -> bool:
    return isinstance(rf, dict) and rf.get('type') == 'json_schema' and isinstance(rf.get('json_schema'), dict)

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    fmt = OpenAIAssistantAgent.configure_response_format(response_format)
except AgentInitializationException as e:
    if 'json_schema' in str(e):
        fmt = OpenAIAssistantAgent.configure_response_format(SomeModelClass)

When it happens

Trigger: Passing response_format={'type':'json_schema','json_schema':'my-schema-name'} (string instead of dict), or omitting json_schema, or passing it as a pydantic model instance instead of its serialized dict form.

Common situations: Confusing the schema name string with the schema object; passing a BaseModel class where the dict form is expected; truncated/copy-pasted response_format config; version skew where the expected shape changed.

Related errors

• Encountered unexpected response_format type: {resp_type}. Al
• response_format must be a dictionary, a subclass of BaseMode
• Failed to create OpenAI settings.
• The OpenAI API key is required.
• The OpenAI model ID is required.

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