Enable non-strict output types

rm-openai · rm-openai · commit 8e30b01ed8b4 · 2025-04-18T14:53:52.000-04:00
diff --git a/examples/basic/non_strict_output_type.py b/examples/basic/non_strict_output_type.py
@@ -0,0 +1,46 @@
+import asyncio
+from dataclasses import dataclass
+
+from agents import Agent, Runner
+
+"""This example demonstrates how to use an output type that is not in strict mode. Strict mode
+allows us to guarantee valid JSON output, but some schemas are not strict-compatible.
+
+In this example, we define an output type that is not strict-compatible, and then we run the
+agent with strict_json_schema=False.
+
+To understand which schemas are strict-compatible, see:
+https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses#supported-schemas
+"""
+
+
+@dataclass
+class OutputType:
+    jokes: dict[int, str]
+    """A list of jokes, indexed by joke number."""
+
+
+async def main():
+    agent = Agent(
+        name="Assistant",
+        instructions="You are a helpful assistant.",
+        output_type=OutputType,
+    )
+
+    input = "Tell me 3 short jokes."
+
+    # First, let's try with a strict output type. This should raise an exception.
+    try:
+        result = await Runner.run(agent, input)
+        raise AssertionError("Should have raised an exception")
+    except Exception as e:
+        print(f"Error: {e}")
+
+    # Now let's try again with a non-strict output type. This should work.
+    agent.output_schema_strict = False
+    result = await Runner.run(agent, input)
+    print(result.final_output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/src/agents/agent.py b/src/agents/agent.py
@@ -144,6 +144,14 @@ class Agent(Generic[TContext]):
     output_type: type[Any] | None = None
     """The type of the output object. If not provided, the output will be `str`."""
 
+    output_schema_strict: bool = True
+    """Whether the output JSON schema passed to the LLM should be strict.
+
+    We **strongly** recommend setting this to True, as it increases the likelihood of correct JSON
+    being produced. However, for output types that cannot be converted to strict JSON, you can
+    set this to False.
+    """
+
     hooks: AgentHooks[TContext] | None = None
     """A class that receives callbacks on various lifecycle events for this agent.
     """
diff --git a/src/agents/agent_output.py b/src/agents/agent_output.py
@@ -71,7 +71,14 @@ def __init__(self, output_type: type[Any], strict_json_schema: bool = True):
             self._output_schema = self._type_adapter.json_schema()
 
         if self.strict_json_schema:
-            self._output_schema = ensure_strict_json_schema(self._output_schema)
+            try:
+                self._output_schema = ensure_strict_json_schema(self._output_schema)
+            except UserError as e:
+                raise UserError(
+                    "Strict JSON schema is enabled, but the output type is not valid. "
+                    "Either make the output type strict, or pass output_schema_strict=False to "
+                    "your Agent()"
+                ) from e
 
     def is_plain_text(self) -> bool:
         """Whether the output type is plain text (versus a JSON object)."""
diff --git a/src/agents/run.py b/src/agents/run.py
@@ -934,7 +934,7 @@ def _get_output_schema(cls, agent: Agent[Any]) -> AgentOutputSchema | None:
         if agent.output_type is None or agent.output_type is str:
             return None
 
-        return AgentOutputSchema(agent.output_type)
+        return AgentOutputSchema(agent.output_type, strict_json_schema=agent.output_schema_strict)
 
     @classmethod
     def _get_handoffs(cls, agent: Agent[Any]) -> list[Handoff]:
