Skip to content

docs: document auto_previous_response_id and model_refusal error handler#3383

Open
ioleksiuk wants to merge 1 commit into
openai:mainfrom
ioleksiuk:docs/runner-docstring-drift
Open

docs: document auto_previous_response_id and model_refusal error handler#3383
ioleksiuk wants to merge 1 commit into
openai:mainfrom
ioleksiuk:docs/runner-docstring-drift

Conversation

@ioleksiuk
Copy link
Copy Markdown
Contributor

Summary

Two pieces of doc drift accumulated in the public `Runner` methods:

This PR adds the missing `auto_previous_response_id` entry to each `Args:` block and updates the `error_handlers` description to list both handler kinds.

Test plan

```
$ uv run python -c "
import inspect
from agents import Runner
for name in ('run', 'run_sync', 'run_streamed'):
doc = inspect.getdoc(getattr(Runner, name)) or ''
print(name, 'auto_previous_response_id:', 'auto_previous_response_id' in doc,
'model_refusal:', 'model_refusal' in doc)
"
run auto_previous_response_id: True model_refusal: True
run_sync auto_previous_response_id: True model_refusal: True
run_streamed auto_previous_response_id: True model_refusal: True
```

  • `uv run ruff check src/agents/run.py src/agents/run_config.py` — All checks passed.
  • Docs-only change; no runtime tests apply.

Issue number

N/A — found during a docstring/signature drift audit following recent param/handler additions.

Checks

  • I've added new tests (if relevant) — docs only, no test changes
  • I've added/updated the relevant documentation
  • I've run `make lint` and `make format`
  • I've made sure tests pass

Two pieces of doc drift accumulated:

- PR openai#2117 added the `auto_previous_response_id` parameter to
  `Runner.run`, `Runner.run_sync`, and `Runner.run_streamed` signatures
  but did not document it in the `Args:` blocks.
- PR openai#3057 added `model_refusal` as a supported key in
  `RunErrorHandlers`, but four docstrings still claim
  "Currently supports max_turns" only (three in `run.py`, one in
  `run_config.py:RunOptions.error_handlers`).

Add the missing `auto_previous_response_id` entry to each `Args:` block
and update the `error_handlers` description to list both handler kinds.
Copy link
Copy Markdown
Member

@seratch seratch left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'd like to have only the auto_previous_response_id documentation

Comment thread src/agents/run.py
Comment on lines +242 to +243
error_handlers: Error handlers keyed by error kind. Currently supports
max_turns and model_refusal.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could be outdated. We'd like to avoid listing the possible values here.

Suggested change
error_handlers: Error handlers keyed by error kind. Currently supports
max_turns and model_refusal.
error_handlers: Error handlers keyed by error kind.

Comment thread src/agents/run_config.py

error_handlers: NotRequired[RunErrorHandlers[TContext] | None]
"""Error handlers keyed by error kind. Currently supports max_turns."""
"""Error handlers keyed by error kind. Currently supports max_turns and model_refusal."""
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same as above

@seratch seratch added documentation Improvements or additions to documentation feature:core labels May 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation feature:core

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants