[Release] openai/openai-agents-python v0.15.0: v0.15.0

OpenAI Agents Python v0.15.0 introduces explicit model refusal handling through a new `ModelRefusalError` exception, replacing previous behavior where refusals were treated as empty output or caused retry loops. The release includes a `model_refusal` error handler that allows developers to gracefully handle refusals without raising exceptions. For structured-output agents, handlers can return values matching the output schema for validation. Additional updates include documentation improvements and dependency bumps.

Key Points

• •Model refusals are now surfaced explicitly as `ModelRefusalError` instead of empty text or retry loops
• •Use `error_handlers={"model_refusal": lambda data: data.error.refusal}` to handle refusals without raising exceptions
• •For structured-output agents, `model_refusal` handlers can return values matching the agent's output schema
• •SDK validates refusal handler outputs like other run error handler final outputs
• •Breaking change: code expecting `final_output == ""` for refusals needs to be updated to use the new handler pattern
• •Refusal handling applies to both sync and async Runner execution modes
• •Dependency updates include GitHub Actions, PyPI publish action, and Codex action versions

Workflow Diagram

Concepts

Artifacts (2)

result = Runner.run_sync(
    agent,
    input,
    error_handlers={"model_refusal": lambda data: data.error.refusal},
)

# For structured-output agents, handler can return a value matching the output schema
result = Runner.run_sync(
    agent,
    input,
    error_handlers={
        "model_refusal": lambda data: {
            "status": "refused",
            "reason": data.error.refusal
        }
    },
)