Allow sending custom delta events in streaming loop

[markb-trustifi]

Please read this first

• Have you read the docs? yes
• Have you searched for related issues? yes

Describe the feature

Please add support for sending custom delta events from the tool execute function when the loop runs in stream. Right now it is possible only with a hack. It will be nice to have it built-in.

const agent = new Agent({
   name: 'agent',
   tools: [tool({
      name: "mytool",
      execute: async (args, runContext, {toolCall}) => {
         const generator = getLongGenerator();
          for await (let event of result) {
              if (runContext.context.result && !runContext.context.result.cancelled) {
                    runContext.context.result._addItem({name: 'custom_event', item: event, type: 'run_item_stream_event'});
              }
          }
      }
   })]
});

const runnerOptions = {context: {}, stream: true};
const result = await run(agent, prompt, runnerOptions);
runnerOptions.context.result = result;
for await (let event of result) {
   yield event;    //combined original and custom events
}
await result.completed;

Such custom events doesn't enter into the run history. They are transparent for state.

[seratch]

Thanks for sharing this feedback.

I think this depends on what an app wants to do with those events. If the events are UI-only progress updates and should not affect run history or model state, I do not think the runner stream necessarily needs to own them. The app can keep an app-level event channel and merge it with the SDK stream at the transport boundary.

If we support this in the SDK, I would avoid overloading run_item_stream_event, because those events currently represent SDK-created RunItems. A separate custom_stream_event or an explicit tool progress callback would be cleaner, but we don't plan to add such in the short term.

[markb-trustifi]

Hi,
An explicit tool progress callback with custom message will be fine too.