{"record":{"id":"cdd2f64f23f0302f","repo":"microsoft/semantic-kernel","slug":"only-json-schema-is-allowed-from-that-helper","errorCode":null,"errorMessage":"Only 'json_schema' is allowed from that helper.","messagePattern":"Only 'json_schema' is allowed from that helper\\.","errorType":"exception","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/open_ai/openai_responses_agent.py","lineNumber":790,"sourceCode":"                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\"),\n                    \"strict\": interim_format.get(\"strict\", True),\n                }\n            else:\n                # Build a schema from a plain Python class\n                generated_schema = KernelJsonSchemaBuilder.build(parameter_type=response_format, structured_output=True)\n                if generated_schema is None:\n                    raise AgentInitializationException(f\"Could not generate schema for the type {response_format}.\")\n                configured_format = {\n                    \"type\": \"json_schema\",\n                    \"name\": response_format.__name__,\n                    \"schema\": generated_schema,\n                    \"strict\": True,\n                }\n        else:","sourceCodeStart":772,"sourceCodeEnd":808,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/open_ai/openai_responses_agent.py#L772-L808","documentation":"Raised by configure_response_format() on the BaseModel branch: type_to_text_format_param(response_format) returned an interim format whose 'type' is not 'json_schema'. The helper is expected to produce a json_schema format for a pydantic model; any other type indicates the model could not be represented as strict JSON schema and is unsupported here.","triggerScenarios":"Passing a pydantic BaseModel subclass whose fields/annotations type_to_text_format_param cannot convert into a json_schema response format (e.g. unsupported field types, custom annotations the helper rejects).","commonSituations":"Using a BaseModel with exotic field types (unions the SDK can't make strict, generic types, forward refs unresolved), or an openai SDK version where the helper returns 'text' for models it can't handle. The Responses structured-output path only accepts json_schema.","solutions":["Simplify the BaseModel to fields with JSON-schema-compatible types (str, int, float, bool, nested BaseModel, list).","Resolve any forward references / rebuild the model before passing it.","Update the openai SDK to a version whose type_to_text_format_param supports your model shape.","As a fallback, build the json_schema dict manually and pass it via the dict path."],"exampleFix":"// before\nclass Out(BaseModel):\n    value: Any  # unsupported\ncfg = OpenAIResponsesAgent.configure_response_format(Out)\n\n// after\nclass Out(BaseModel):\n    value: str\ncfg = OpenAIResponsesAgent.configure_response_format(Out)","handlingStrategy":"type-guard","validationCode":"from openai.lib._parsing._responses import type_to_text_format_param\nif isinstance(response_format, type):\n    interim = type_to_text_format_param(response_format)\n    assert interim['type'] == 'json_schema', 'helper did not produce json_schema'","typeGuard":"def model_produces_json_schema(model_cls: type) -> bool:\n    from openai.lib._parsing._responses import type_to_text_format_param\n    try:\n        return type_to_text_format_param(model_cls)['type'] == 'json_schema'\n    except Exception:\n        return False","tryCatchPattern":"from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException\ntry:\n    cfg = OpenAIResponsesAgent.configure_response_format(MyModel)\nexcept AgentInitializationException as e:\n    if \"helper\" in str(e):\n        # simplify model fields or build schema dict manually\n        cfg = OpenAIResponsesAgent.configure_response_format({'type': 'json_schema', 'json_schema': {...}})\n    raise","preventionTips":["Keep BaseModel fields to JSON-schema-compatible types.","Resolve forward references (Model.model_rebuild()) before use.","If the helper rejects the model, supply a hand-built json_schema dict."],"tags":["response-format","pydantic","json-schema"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}