Support for Streaming Events from Long-Running Tools

[noe-starlight]

Add support in the OpenAI Agents SDK for tools that:
• Run long-running operations (e.g. background tasks, indexing, data processing)
• Connect to WebSockets or other asynchronous event sources
And allow those tools to stream intermediate updates or status events back to the agent runtime via custom event channels.

Motivation:

In real-world agent applications, tools often perform actions that span longer than a few seconds or need to respond to external events (e.g., via WebSocket, SSE, or polling). The current SDK does not allow for easily streaming intermediate updates from tools. Developers are forced to block until a final result or create workarounds outside the agent runtime.

This limits the user experience and utility for:
• Background processing tools (e.g. book indexing, media analysis)
• Real-time systems (e.g. stock price streams, WebSocket bots)
• Long API workflows (e.g. transcription, document conversion)

Proposed API Behavior:

Allow tools to yield structured event objects (e.g., tool_stream_event, tool_background_task) that the agent runtime can surface to the user (through a developer-defined channel such as SSE or a UI event handler).

Example tool yield behavior:

yield {"type": "tool_background_task", "tool_name": "book_indexer", "message": "Indexing book contents started"}

for i in range(10):
    yield {"type": "tool_stream_event", "tool_name": "book_indexer", "data": f"Indexing page {i+1} of 10"}

Developer stream output handler (e.g. in Flask):

if tool_event.get("type") == "tool_stream_event":
    yield f'data: {json.dumps({"event": "tool_update", "tool_name": tool_event["tool_name"], "detail": tool_event["data"]})}\n\n'
elif tool_event.get("type") == "tool_background_task":
    yield f'data: {json.dumps({"event": "tool_background_task_started", "tool_name": tool_event["tool_name"], "detail": tool_event["message"]})}\n\n'

Expected output

event: tool_background_task_started
tool_name: book_indexer
detail: "Indexing book contents"

event: tool_update
tool_name: book_indexer
detail: "Indexing page 1 of 10"

event: tool_update
tool_name: book_indexer
detail: "Indexing page 2 of 10"

Benefits:
• Enhances interactivity of tools without needing to return blocking responses
• Improves UX in agent-hosted environments with real-time feedback
• Enables developers to build more robust and scalable agents with observable internal progress

[seratch]

Thanks for sharing this. While OpenAI platform released background mode and webhooks for Responses API, this SDK does not yet natively support the functionality. We cannot tell whether and when something would be added to this SDK, but I agree some enhancement would be useful for the use case.