feat: #1333 add custom stream events support for tool functions

[vincenzodomina]

This adds support to add custom streaming events from within tool functions to e.g. send progress update messages for long running tools without breaking changes.

• No behavior change for existing tools; the new emit_event() method is opt-in.
• Non-streamed runs simply no-op emit_event (no emitter is set).
• Minimal surface change; no new stream types introduced.

This addition solves issue #1333 and could be used for #692 and #661

Changes:

• src/agents/stream_events.py
  • Extended RunItemStreamEvent.name to accept "tool_event" so we can reuse RunItemStreamEvent without new types.
• src/agents/run_context.py
  • Added an internal emitter and current agent fields to RunContextWrapper:
  • Added async def emit_event(self, event: Mapping[str, Any]) -> None:
• src/agents/run.py
  • After creating RunResultStreaming and context_wrapper, wired an async _emit that enqueues to
  • Kept context_wrapper._current_agent updated each turn.

How to use (inside tools):

1. In any tool function (receives ToolContext, which inherits RunContextWrapper), you can now do:

await ctx.emit_event({"type": "data-my_tool.step", "data": {"message": "Working..."}})

2. The event flows through the SDK’s stream as a RunItemStreamEvent with name "tool_event" and item.raw_item. You can than forward that event as is to your stream consumer.

3. From your stream consumer re-yield these events:

result = Runner.run_streamed(...)
async for event in result.stream_events():
    if event.type == "run_item_stream_event" and event.name == "tool_event":
        yield event.item.raw_item

[seratch]

You can do the same by starting a task (or thread) for the same operation using on_tool_start/on_tool_end: https://github.com/openai/openai-agents-python/blob/main/examples/basic/lifecycle_example.py We'd like to hold off adding this custom event for now.

[dfliess]

hey @seratch on_tool_start/on_tool_end are useful, but they don’t cover cases where a tool needs to emit multiple intermediate updates from inside the tool "body". External shared state or event bus may work , but make tools much more complex. Having an official way for tools to emit mid-execution events (like emit_event) would make DevX better and responsive UIs and long-running workflows much easier to build.