microsoft/semantic-kernel · error · AgentInitializationException

Only 'json_schema' is allowed from that helper.

Error message

Only 'json_schema' is allowed from that helper.

What it means

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.

Source

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

                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"),
                    "strict": interim_format.get("strict", True),
                }
            else:
                # Build a schema from a plain Python class
                generated_schema = KernelJsonSchemaBuilder.build(parameter_type=response_format, structured_output=True)
                if generated_schema is None:
                    raise AgentInitializationException(f"Could not generate schema for the type {response_format}.")
                configured_format = {
                    "type": "json_schema",
                    "name": response_format.__name__,
                    "schema": generated_schema,
                    "strict": True,
                }
        else:

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Simplify the BaseModel to fields with JSON-schema-compatible types (str, int, float, bool, nested BaseModel, list).
  2. Resolve any forward references / rebuild the model before passing it.
  3. Update the openai SDK to a version whose type_to_text_format_param supports your model shape.
  4. As a fallback, build the json_schema dict manually and pass it via the dict path.

Example fix

// before
class Out(BaseModel):
    value: Any  # unsupported
cfg = OpenAIResponsesAgent.configure_response_format(Out)

// after
class Out(BaseModel):
    value: str
cfg = OpenAIResponsesAgent.configure_response_format(Out)
Defensive patterns

Strategy: type-guard

Validate before calling

from openai.lib._parsing._responses import type_to_text_format_param
if isinstance(response_format, type):
    interim = type_to_text_format_param(response_format)
    assert interim['type'] == 'json_schema', 'helper did not produce json_schema'

Type guard

def model_produces_json_schema(model_cls: type) -> bool:
    from openai.lib._parsing._responses import type_to_text_format_param
    try:
        return type_to_text_format_param(model_cls)['type'] == 'json_schema'
    except Exception:
        return False

Try / catch

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    cfg = OpenAIResponsesAgent.configure_response_format(MyModel)
except AgentInitializationException as e:
    if "helper" in str(e):
        # simplify model fields or build schema dict manually
        cfg = OpenAIResponsesAgent.configure_response_format({'type': 'json_schema', 'json_schema': {...}})
    raise

Prevention

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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