feat(prebuilt): structured output error handling with configurable retry policy

[casparb]

This PR adds error handling and retry mechanisms for create_agent structured output via a handle_errors parameter in ToolOutput.

Changes:

• Adds MultipleStructuredOutputsError exception for when models incorrectly call multiple structured output tools simultaneously
• Adds StructuredOutputParsingError exception for when tool arguments fail to parse according to the schema
• Implements automatic error handling logic that re-prompts the model with a configurable error message when structured output failures occur via handle_errors policy in ToolOutput:

class ToolOutput:
    ...
    handle_errors: Union[
        bool,                         # True: retry all, False: no retry
        str,                          # Custom static error message for all errors
        type[Exception],              # Retry only this exception type
        tuple[type[Exception], ...],  # Retry only these exception types
        Callable[[Exception], str],   # Custom callable returning error message
    ]
    """Error handling strategy. Default: True (retry on all error types with default error message)"""

Examples:

# Retry all errors
ToolOutput(WeatherReport)

# No retry
ToolOutput(WeatherReport, handle_errors=False)

# Custom message for all errors
ToolOutput(WeatherReport, handle_errors="Please provide valid data")

# Only retry specific error type
ToolOutput(WeatherReport, handle_errors=StructuredOutputParsingError)

# Multiple error types
ToolOutput(WeatherReport, handle_errors=(MultipleStructuredOutputsError, StructuredOutputParsingError))

# Custom logic
ToolOutput(
    Union[WeatherReport, LocationInfo],
    handle_errors=lambda e: "Only one response please" if isinstance(e, MultipleStructuredOutputsError) else "Invalid format"
)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
langgraph-docs-preview	Ignored	Preview		Aug 26, 2025 0:59am

[sydney-runkle]

By default, we want to retry when a model calls multiple structured output tools right?

One other thing I want to think about (can be in my PR), we might want to support this in ToolNode as well, so like AgentRetryPolicy might be a better name...

[sydney-runkle]

Ah one other follow up - why introduce the cognitive overhead of a retry dataclass right now?

should we just do a callable? that offers the same impact and is less complex

[sydney-runkle]

Nice work on testing.

Please update description of PR + docstrings as well!