Skip to content

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

Draft
adityasingh2400 wants to merge 2 commits intoopenai:mainfrom
adityasingh2400:feat/reasoning-delta-stream-event-825
Draft

feat(streaming): emit ReasoningDeltaEvent for reasoning/thinking deltas#2913
adityasingh2400 wants to merge 2 commits intoopenai:mainfrom
adityasingh2400:feat/reasoning-delta-stream-event-825

Conversation

@adityasingh2400
Copy link
Copy Markdown
Contributor

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

Ubuntu and others added 2 commits April 16, 2026 16:08
…as (openai#825)

Add a new ReasoningDeltaEvent to StreamEvent so callers can react to
reasoning/thinking tokens in real time without unpacking low-level raw
response events.

The event is emitted whenever a ResponseReasoningSummaryTextDeltaEvent
(o-series extended thinking via the Responses API) or a
ResponseReasoningTextDeltaEvent (third-party models like DeepSeek-R1
via LiteLLM) passes through the stream.  The underlying
RawResponsesStreamEvent is still emitted as well, so nothing breaks for
consumers that already inspect raw events.

Fields:
  delta    - the incremental text fragment from this chunk
  snapshot - full accumulated reasoning text so far in this turn
  type     - always 'reasoning_delta'

Closes openai#825
- Import ResponseCreatedEvent and reset _reasoning_snapshot to "" when
  a ResponseCreatedEvent is received inside the retry stream loop, fixing
  the bug where snapshot text would be duplicated across retries
- In test_reasoning_delta_event_type_field: add found=False flag and
  assert found after the loop so the test properly fails when no
  ReasoningDeltaEvent is emitted
@github-actions github-actions bot added enhancement New feature or request feature:core labels Apr 16, 2026
@seratch seratch marked this pull request as draft April 17, 2026 04:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request feature:core

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Yield reasoning delta in the response or add hooks to handle

1 participant