Step 1 of 4
Design the event protocol
Streaming without structure is just faster confusion.
Design a typed streaming event protocol for the agent. Event types to include: run_started {run_id}, text_delta {content}, tool_started {call_id, tool, args_summary}, tool_progress {call_id, note} (optional heartbeats), tool_finished {call_id, ok, result_summary}, turn_completed {turn}, run_completed {status, usage}, run_error {message}, run_cancelled {partial: bool}. Each event carries a sequence number and timestamp. Document the protocol in a schema file with versioning (v1). Decide the transport (SSE for one-way UI updates is the default choice) and justify it in one paragraph.
Expected after this step
A versioned, typed event protocol document.
Should not happen
- ✕Buffering the entire response and calling a spinner 'streaming'
- ✕Interleaving raw tool JSON into the text stream and breaking the client
- ✕Cancellation that kills the process but leaves files half-edited
- ✕No heartbeat during long tool runs so users still think it froze
Verify before continuing
Do not move on until every check is true. The complete button stays locked until then.
Do not continue if…
- !Buffering the entire response and calling a spinner 'streaming'
- !Interleaving raw tool JSON into the text stream and breaking the client
- !Cancellation that kills the process but leaves files half-edited
- !No heartbeat during long tool runs so users still think it froze
If the AI messes this up
Use this when the AI fakes progress or breaks the feature. It forces a real fix.
The design streams raw text with markers spliced in. Replace it with typed events - clients must switch on event.type, never regex the stream.