{"record":{"id":"1c0c6c68bfdbb229","repo":"microsoft/semantic-kernel","slug":"if-response-format-has-type-json-schema-json-s","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_assistant_agent.py","lineNumber":669,"sourceCode":"\n        Args:\n            response_format: The response format.\n\n        Returns:\n            AssistantResponseFormatOptionParam: The response format.\n        \"\"\"\n        if response_format is None or response_format == \"auto\":\n            return None\n\n        configured_response_format = None\n        if isinstance(response_format, dict):\n            resp_type = response_format.get(\"type\")\n            if resp_type == \"json_object\":\n                configured_response_format = {\"type\": \"json_object\"}\n            elif 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                configured_response_format = response_format  # type: ignore\n            else:\n                raise AgentInitializationException(\n                    f\"Encountered unexpected response_format type: {resp_type}. Allowed types are `json_object` \"\n                    \" and `json_schema`.\"\n                )\n        elif isinstance(response_format, type):\n            # If it's a type, differentiate based on whether it's a BaseModel subclass\n            if issubclass(response_format, BaseModel):\n                configured_response_format = type_to_response_format_param(response_format)  # type: ignore\n            else:\n                generated_schema = KernelJsonSchemaBuilder.build(parameter_type=response_format, structured_output=True)\n                assert generated_schema is not None  # nosec\n                configured_response_format = generate_structured_output_response_format_schema(\n                    name=response_format.__name__, schema=generated_schema","sourceCodeStart":651,"sourceCodeEnd":687,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/open_ai/openai_assistant_agent.py#L651-L687","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass a full schema dict: {'type':'json_schema','json_schema':{'name':'...','schema':{...}}} matching OpenAI's structured output format.","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.","Validate isinstance(response_format['json_schema'], dict) before calling."],"exampleFix":"# before\nresponse_format={'type':'json_schema','json_schema':'MyModel'}\nfmt = OpenAIAssistantAgent.configure_response_format(response_format)\n\n# after\nresponse_format={'type':'json_schema','json_schema':{'name':'MyModel','schema':{'type':'object','properties':{...}}}}\nfmt = OpenAIAssistantAgent.configure_response_format(response_format)","handlingStrategy":"validation","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_response_format(rf) -> bool:\n    return isinstance(rf, dict) and rf.get('type') == 'json_schema' and isinstance(rf.get('json_schema'), dict)","tryCatchPattern":"from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException\ntry:\n    fmt = OpenAIAssistantAgent.configure_response_format(response_format)\nexcept AgentInitializationException as e:\n    if 'json_schema' in str(e):\n        fmt = OpenAIAssistantAgent.configure_response_format(SomeModelClass)","preventionTips":["Pass the full json_schema dict, not a name string.","Prefer passing a BaseModel subclass for structured outputs.","Validate the dict shape before calling."],"tags":["configuration","agents","openai-assistant","response-format","structured-outputs"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}