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. The Responses API expects a structured object under that key; a non-dict (string, None, list) cannot be forwarded. The method validates shape before passing the dict through unchanged.

Source

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

        Args:
            response_format: The response format.

        Returns:
            The final dict containing `text.format` if JSON-based, or None if "auto".
        """
        if response_format is None or response_format == "auto":
            return None

        # TODO(evmattso): improve typing in this method
        if isinstance(response_format, dict):
            resp_type = response_format.get("type", None)

            if resp_type == "json_object":
                return {"type": "json_object"}
            if 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
                return response_format  # type: ignore

            raise AgentInitializationException(
                f"Encountered unexpected response_format type: {resp_type}. Allowed types are `json_object` "
                " and `json_schema`."
            )
        if isinstance(response_format, type):
            if issubclass(response_format, BaseModel):
                interim_format = type_to_text_format_param(response_format)
                if interim_format["type"] != "json_schema":
                    raise AgentInitializationException("Only 'json_schema' is allowed from that helper.")
                configured_format = {
                    "type": "json_schema",
                    "name": interim_format.get("name", response_format.__name__),
                    "schema": interim_format.get("schema"),

View on GitHub (pinned to c028a0c7dc)

Solutions

Ensure the 'json_schema' value is a real dict: json.loads() any string before assigning it.
Pass a pydantic BaseModel subclass or a typed class instead, and let configure_response_format() build the schema for you.
Validate with isinstance(fmt.get('json_schema'), dict) before calling.

Example fix

// before
fmt = {"type": "json_schema", "json_schema": schema_json_string}
cfg = OpenAIResponsesAgent.configure_response_format(fmt)

// after
fmt = {"type": "json_schema", "json_schema": json.loads(schema_json_string)}
cfg = OpenAIResponsesAgent.configure_response_format(fmt)

Defensive patterns

Strategy: type-guard

Validate before calling

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'

Type guard

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

Try / catch

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    cfg = OpenAIResponsesAgent.configure_response_format(fmt)
except AgentInitializationException as e:
    if 'json_schema' in str(e) and isinstance(fmt.get('json_schema'), str):
        import json
        fmt['json_schema'] = json.loads(fmt['json_schema'])
        cfg = OpenAIResponsesAgent.configure_response_format(fmt)
    raise

Prevention

Always parse JSON strings into dicts before placing them under 'json_schema'.
Prefer passing a BaseModel subclass and let the method build the schema.
Validate the dict shape with isinstance before calling.

When it happens

Trigger: Passing response_format={'type': 'json_schema', 'json_schema': '{...}'} (a JSON string instead of parsed dict), or {'type': 'json_schema', 'json_schema': None}, or omitting a valid schema object.

Common situations: Loading a response format from a JSON string and forgetting to json.loads() it, building the dict dynamically and leaving the schema slot empty, or confusing the OpenAI Chat Completions json_schema envelope with the Responses envelope.

Related errors

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