feat(streaming): emit ReasoningDeltaEvent for reasoning/thinking deltas

[adityasingh2400]

Summary

When models like o3 or DeepSeek-R1 produce reasoning/thinking tokens during streaming, those deltas currently only surface as raw RawResponsesStreamEvent wrappers around low-level response.reasoning_summary_text.delta or response.reasoning_text.delta events. To consume them, callers have to inspect .data.type and cast the event themselves — there's no clean signal in the StreamEvent union.

This PR adds ReasoningDeltaEvent to StreamEvent and emits it alongside the existing raw event so reasoning deltas are as easy to consume as message deltas.

Closes #825

What changed

• Added ReasoningDeltaEvent dataclass to stream_events.py with delta, snapshot, and type fields
• Updated StreamEvent type alias to include ReasoningDeltaEvent
• Exported from agents/__init__.py
• In run_internal/run_loop.py, the run_single_turn_streamed loop now emits a ReasoningDeltaEvent after each ResponseReasoningSummaryTextDeltaEvent (o-series) and ResponseReasoningTextDeltaEvent (DeepSeek/LiteLLM)
• The snapshot field accumulates the full reasoning text so far in the turn, so callers don't have to maintain their own buffer
• Raw events are still emitted unchanged — fully backwards compatible

Usage example

from agents import Agent, Runner
from agents.stream_events import ReasoningDeltaEvent

agent = Agent(name="thinker", model="o3-mini")
result = Runner.run_streamed(agent, "prove P != NP")

async for event in result.stream_events():
    if isinstance(event, ReasoningDeltaEvent):
        print(event.delta, end="", flush=True)

print()  # reasoning complete

Tests

Added tests/test_reasoning_delta_stream_event.py covering:

• ReasoningDeltaEvent is emitted for reasoning items
• Snapshot grows monotonically and ends with full text
• No event emitted for plain text responses
• Raw events still emitted alongside
• Importable directly from agents
• Correct dataclass fields

Also updated tests/test_stream_events.py::test_complete_streaming_events to account for the new event in the event sequence (count goes from 27 → 28).

Summary by CodeRabbit

• New Features

  • Added ReasoningDeltaEvent for streaming incremental reasoning updates from AI agents, featuring:
    • delta: incremental reasoning fragment
    • snapshot: accumulated reasoning text
    • Emitted during agent streaming when reasoning is available

• Tests

  • Added comprehensive tests validating reasoning delta streaming behavior and event accumulation

[github-actions]

This PR is stale because it has been open for 10 days with no activity.

[adityasingh2400]

@seratch friendly bump — this has been waiting on review since #825 was opened. Happy to rebase or split if it's blocked on scope.

[github-actions]

This PR is stale because it has been open for 10 days with no activity.

[adityasingh2400]

Bumping after the stale-bot ping. I just rebased onto current main and CI is still green across the 5-file diff. The change stays narrow, one new ReasoningDeltaEvent type, a small emit path in run_loop, and tests. Happy to split the docs/example out into a follow-up PR if that helps land the core type sooner. cc @rm-openai @seratch when you have a moment.

[seratch]

@adityasingh2400 Thanks for sharing this. This change could drastically increase the number of events that could be sent, so we hesitate changing the default behavior in this way for now.

[adityasingh2400]

Thanks for the read. Totally fair point on event volume. Would you accept the change behind an opt-in flag so the default stream stays unchanged? I can gate emission behind a RunConfig flag (e.g. emit_reasoning_deltas defaulting to False) so anyone with a reasoning UI can opt in, and existing consumers see identical event counts.

If you'd prefer to close this and reopen as the gated version, happy to do that too.

[adityasingh2400]

I went ahead and gated this behind an opt-in flag so the default behavior is unchanged. I added RunConfig.emit_reasoning_deltas, defaulting to False. When it is False the runner emits exactly the same events as before, so existing consumers see no change in event volume. Setting it to True turns on ReasoningDeltaEvent for anyone building a reasoning UI.

The two emission points in run_single_turn_streamed are now wrapped in that flag check, and I added a test asserting no ReasoningDeltaEvent is emitted by default plus updated the existing streaming tests to opt in. Locally ruff format, ruff lint, mypy on the two changed source files, and the full tests/test_stream_events.py and tests/test_reasoning_delta_stream_event.py suites all pass. Let me know if you would prefer the flag live somewhere other than RunConfig.