{"record":{"id":"9caf31d3c545b671","repo":"microsoft/semantic-kernel","slug":"if-response-format-has-type-json-schema-json-s-9caf31","errorCode":null,"errorMessage":"If response_format has type 'json_schema', 'json_schema' must be a valid dictionary.","messagePattern":"If response_format has type 'json_schema', 'json_schema' must be a valid dictionary\\.","errorType":"exception","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/open_ai/openai_responses_agent.py","lineNumber":776,"sourceCode":"        Args:\n            response_format: The response format.\n\n        Returns:\n            The final dict containing `text.format` if JSON-based, or None if \"auto\".\n        \"\"\"\n        if response_format is None or response_format == \"auto\":\n            return None\n\n        # TODO(evmattso): improve typing in this method\n        if isinstance(response_format, dict):\n            resp_type = response_format.get(\"type\", None)\n\n            if resp_type == \"json_object\":\n                return {\"type\": \"json_object\"}\n            if resp_type == \"json_schema\":\n                json_schema = response_format.get(\"json_schema\")  # type: ignore\n                if not isinstance(json_schema, dict):\n                    raise AgentInitializationException(\n                        \"If response_format has type 'json_schema', 'json_schema' must be a valid dictionary.\"\n                    )\n                # We're assuming the response_format has already been provided in the correct format\n                return response_format  # type: ignore\n\n            raise AgentInitializationException(\n                f\"Encountered unexpected response_format type: {resp_type}. Allowed types are `json_object` \"\n                \" and `json_schema`.\"\n            )\n        if isinstance(response_format, type):\n            if issubclass(response_format, BaseModel):\n                interim_format = type_to_text_format_param(response_format)\n                if interim_format[\"type\"] != \"json_schema\":\n                    raise AgentInitializationException(\"Only 'json_schema' is allowed from that helper.\")\n                configured_format = {\n                    \"type\": \"json_schema\",\n                    \"name\": interim_format.get(\"name\", response_format.__name__),\n                    \"schema\": interim_format.get(\"schema\"),","sourceCodeStart":758,"sourceCodeEnd":794,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/open_ai/openai_responses_agent.py#L758-L794","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nfmt = {\"type\": \"json_schema\", \"json_schema\": schema_json_string}\ncfg = OpenAIResponsesAgent.configure_response_format(fmt)\n\n// after\nfmt = {\"type\": \"json_schema\", \"json_schema\": json.loads(schema_json_string)}\ncfg = OpenAIResponsesAgent.configure_response_format(fmt)","handlingStrategy":"type-guard","validationCode":"if isinstance(response_format, dict) and response_format.get('type') == 'json_schema':\n    assert isinstance(response_format.get('json_schema'), dict), 'json_schema must be a dict'","typeGuard":"def is_valid_json_schema_format(fmt: dict) -> bool:\n    return fmt.get('type') == 'json_schema' and isinstance(fmt.get('json_schema'), dict)","tryCatchPattern":"from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException\ntry:\n    cfg = OpenAIResponsesAgent.configure_response_format(fmt)\nexcept AgentInitializationException as e:\n    if 'json_schema' in str(e) and isinstance(fmt.get('json_schema'), str):\n        import json\n        fmt['json_schema'] = json.loads(fmt['json_schema'])\n        cfg = OpenAIResponsesAgent.configure_response_format(fmt)\n    raise","preventionTips":["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."],"tags":["response-format","json-schema","validation"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}