feat: add max_turns run error handlers

[seratch]

This pull request adds max_turns run error handler support for non-streamed and streamed runs, including structured-output validation and handler result coercion in src/agents/run.py and src/agents/run_internal/run_loop.py. It introduces new handler types/utilities in src/agents/run_error_handlers.py and src/agents/run_internal/error_handlers.py (untracked files), wires the option into RunOptions, and extends max-turns tests in tests/test_max_turns.py. Behavior change: invalid structured outputs returned by handlers now raise UserError, and handler output can be included in history via include_in_history.

from agents import Agent, Runner, RunErrorHandlerInput, RunErrorHandlerResult

async def handle_max_turns(data: RunErrorHandlerInput):
    # if you don't return a result, the max returns error will be raised
    history_len = len(data.run_data.history)
    # you can send either a dict instead or only final_output data
    return RunErrorHandlerResult(
        final_output=f"Summary: processed {history_len} items.",
        # if true, appends the synthesized output to the conversation history
        include_in_history=True,
    )

agent = Agent(name="My Agent", instructions="...")
result = await Runner.run(
    agent,
    input="Summarize this thread",
    max_turns=3,
    error_handlers={"max_turns": handle_max_turns},
)

The returned value can be either:

• {"final_output": f"Summary: {len(data.run_data.history)} items processed.", "include_in_history": True}
• f"Summary: {len(data.run_data.history)} items processed."

The final output data type must be compatible with the structured output data structure when it's enabled.

Some notes:

• this change is based on run mechanism changes by feat: #636 Add human-in-the-loop (HITL) support #2230
• see also: feat(agents-core): add maxTurns error handlers with runData snapshots openai-agents-js#896

[seratch]

@codex review this

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8b5b29450e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5958b26a03

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4bf84b825e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".