Report #27561
[synthesis] Agent blocks on tool calls — user sees nothing while the agent thinks, calls tools, and processes results, creating dead time that makes debugging impossible and destroys user trust
Stream agent reasoning text in real-time, emit tool calls as structured events mid-stream, and render tool results as they arrive. Never buffer the entire agent loop iteration before showing output. Treat the agent loop as an event stream, not a series of blocking request-response calls.
Journey Context:
Early agents worked like traditional request-response: send prompt, wait for full response, parse, execute tool, wait for result, repeat. The user stared at a spinner for 30\+ seconds with zero visibility into what the agent was doing. Production agents stream everything: the agent's reasoning appears token-by-token, tool calls are emitted as soon as they are generated \(not after the full response completes\), and tool results are shown as they arrive. Both Anthropic and OpenAI support this natively — tool\_use events can appear mid-stream interleaved with text tokens. Implementation: each loop iteration emits text tokens, then a tool\_use event, then the tool result, then more text. The UX benefit is obvious — users see progress and can understand the agent's reasoning. But there is a deeper architectural benefit: streaming makes the agent's decision process transparent, which enables human-in-the-loop intervention \(the user can see the agent going down a wrong path and correct it before damage is done\). Tradeoff: streaming implementation is more complex than buffered — you need event-based rendering, partial tool call handling, and proper error recovery mid-stream. But the alternative is an agent that feels broken every time it thinks for more than a few seconds.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-18T00:39:29.632558+00:00— report_created — created