Progress updates for long-running Tools with MAF + AG-UI

[Gabriel Schmith (gabrielschmith)]

I’m trying to understand the recommended way to notify the frontend about the progress of a long-running Tool execution when using MAF + AG-UI.

The expected flow would be something like:

Tool started
→ Searching documents...
→ Processing documents (10/25)...
→ Generating result...
Tool completed

The goal is to stream these updates while the Tool is still running, without creating intermediate assistant messages.

Current workaround for me:

As a workaround, I created a Channel that allows the Tool execution to publish progress updates.

The AG-UI streaming pipeline consumes this channel and emits each progress update as a reasoning event.

Conceptually:

Long-running Tool
│
├── progress ──→ Channel
│ │
├── progress ──→ Channel
│ ↓
│ AG-UI Stream
│ │
│ ↓
│ Reasoning Events
│
└── Tool Result

This works and allows the UI to receive real-time feedback during the Tool execution.

However, using reasoning events to represent Tool progress feels semantically incorrect and couples Tool execution progress with the reasoning lifecycle.

Is there currently a recommended way in MAF + AG-UI to emit progress/events from a running Tool?

If not, would supporting a dedicated Tool progress event (or a generic custom event associated with the toolCallId) be the recommended approach?

[Rakesh Utekar (rakeshutekar)]

Short answer: there is no dedicated tool progress event in AG-UI today, the Custom event is the sanctioned escape hatch for exactly this, and your instinct about a dedicated event is where the protocol is heading.

The AG-UI event set has TextMessage*, ToolCallStart/Args/End/Result, StepStarted/StepFinished, StateSnapshot/StateDelta, Custom, and the run brackets RunStarted/RunFinished/RunError, but nothing purpose built for streaming intermediate progress out of a tool that is still executing. So you are right that reasoning events are the wrong semantic home for this, they belong to the model's thinking, not to a tool's lifecycle.

Two options fit the protocol as it stands:

1. Custom events, keyed to your toolCallId in the payload. This is the documented "anything the standard event types do not cover" hatch, so something like { name: "tool_progress", value: { toolCallId, phase, current, total } } is the clean way to carry your "Processing documents (10/25)" updates and let the frontend associate them with the running tool. It keeps your Channel design but stops overloading the reasoning lifecycle.
2. StepStarted / StepFinished if you only need coarse phase markers ("Searching", "Processing", "Generating") rather than counters.

And your last question, whether a dedicated tool progress event should be the recommended approach, is being actively worked on upstream, so it is a real gap rather than something you are missing: ag-ui-protocol/ag-ui#200 ("Proposal: Explicitly supporting Long Running Tool Calls at protocol level") is the protocol side, and #2558 (".NET, AG-UI Support more AG-UI event types") is the MAF side. Worth following or commenting on both with your use case, since a first class tool progress or long running operation event is exactly what those are aiming at. Until then, Custom events tied to the toolCallId are the recommended pattern.