fix(llm): preserve response format nullability

Author: u9g

livekit-agents/livekit/agents/llm/_strict.py

@@ -7,15 +7,48 @@
 _T = TypeVar("_T")
 
 
-def to_strict_json_schema(model: type[BaseModel] | TypeAdapter[Any]) -> dict[str, Any]:
+def _model_json_schema(model: type[BaseModel] | TypeAdapter[Any]) -> dict[str, Any]:
     if isinstance(model, TypeAdapter):
-        schema = model.json_schema()
-    else:
-        schema = model.model_json_schema()
+        return model.json_schema()
+    return model.model_json_schema()
+
+
+def to_strict_json_schema(model: type[BaseModel] | TypeAdapter[Any]) -> dict[str, Any]:
+    schema = _model_json_schema(model)
+
+    return _ensure_strict_json_schema(schema, path=(), root=schema)
+
+
+def to_strict_tool_json_schema(model: type[BaseModel] | TypeAdapter[Any]) -> dict[str, Any]:
+    schema = _model_json_schema(model)
+    _make_defaults_nullable(schema)
 
     return _ensure_strict_json_schema(schema, path=(), root=schema)
 
 
+def _make_defaults_nullable(json_schema: object) -> None:
+    """Encode defaulted tool arguments as nullable fields for strict schemas.
+
+    OpenAI strict schemas require every property and do not support JSON Schema defaults, so
+    ``null`` represents "use the Python default". Tool argument preparation replaces that value
+    before validation. Response formats intentionally skip this conversion because their output
+    is validated directly against the declared Pydantic nullability.
+    """
+    if isinstance(json_schema, dict):
+        if "default" in json_schema:
+            typ = json_schema.get("type")
+            if isinstance(typ, str):
+                json_schema["type"] = [typ, "null"]
+            elif isinstance(typ, list) and "null" not in typ:
+                json_schema["type"] = [*typ, "null"]
+
+        for value in json_schema.values():
+            _make_defaults_nullable(value)
+    elif isinstance(json_schema, list):
+        for value in json_schema:
+            _make_defaults_nullable(value)
+
+
 # from https://platform.openai.com/docs/guides/function-calling?api-mode=responses&strict-mode=disabled#strict-mode
 # Strict mode
 # Setting strict to true will ensure function calls reliably adhere to the function schema,
@@ -118,19 +151,6 @@ def _ensure_strict_json_schema(
     if "default" in json_schema:
         json_schema.pop("default", None)
 
-        # Treat any parameter with a default value as optional. If the parameter’s type doesn't
-        # support None, the default will be used instead.
-        t = json_schema.get("type")
-        if isinstance(t, str):
-            json_schema["type"] = [t, "null"]
-
-        elif isinstance(t, list):
-            types = t.copy()
-            if "null" not in types:
-                types.append("null")
-
-            json_schema["type"] = types
-
     json_schema.pop("title", None)
     json_schema.pop("discriminator", None)
 

livekit-agents/livekit/agents/llm/utils.py

@@ -239,7 +239,7 @@ def build_strict_openai_schema(
     """strict mode tool description"""
     model = function_arguments_to_pydantic_model(function_tool)
     info = function_tool.info
-    schema = _strict.to_strict_json_schema(model)
+    schema = _strict.to_strict_tool_json_schema(model)
 
     return {
         "type": "function",

tests/test_response_format.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import pytest
+from pydantic import BaseModel
+
+from livekit.agents.llm import function_tool
+from livekit.agents.llm.utils import build_strict_openai_schema, to_openai_response_format
+
+pytestmark = pytest.mark.unit
+
+
+class _ResponseFormat(BaseModel):
+    label: str = ""
+    description: str | None = None
+
+
+def test_response_format_preserves_pydantic_nullability() -> None:
+    response_format = to_openai_response_format(_ResponseFormat)
+    schema = response_format["json_schema"]["schema"]
+
+    assert schema["required"] == ["label", "description"]
+    assert schema["properties"]["label"]["type"] == "string"
+    assert schema["properties"]["description"]["type"] == ["string", "null"]
+    assert "default" not in schema["properties"]["label"]
+    assert "default" not in schema["properties"]["description"]
+
+
+def test_strict_tool_schema_keeps_defaulted_arguments_nullable() -> None:
+    @function_tool
+    async def lookup(label: str = "") -> str:
+        """Look up an item by label."""
+        return label
+
+    schema = build_strict_openai_schema(lookup)["function"]["parameters"]
+
+    assert schema["properties"]["label"]["type"] == ["string", "null"]