Multi-agent Streaming
Stream coordinator output while surfacing nested specialist-agent progress.
Use multi-agent streaming when one coordinator agent delegates work to specialist agents and the caller should see progress while the specialists run. The coordinator still owns the final answer, but the UI can show nested child-agent activity through agent_tool_event.
Scenario
An incident coordinator receives a customer-impact report. It delegates to support, engineering, and communications specialists. The user sees the coordinator's final brief stream in normally, while each specialist's progress appears in grouped status panels.
When to Use It
Use this pattern when:
- one coordinator should decide which specialists to call
- specialist work may take long enough that hidden progress feels stalled
- the UI should group nested progress by specialist or tool call
- the final answer should still come from one coordinator
- child-agent progress should be replayable or inspectable after the run
Do not use this pattern just to run known independent work. Use parallel pipelines when every branch should run and the coordinator does not need to decide.
Architecture Shape
| Layer | Responsibility |
|---|---|
| coordinator agent | decides which specialists to call and writes the final response |
| specialist agents | own narrow role instructions and return focused findings |
| streaming agent tools | expose specialists with asTool({ stream: true }) |
| request runner | applies trace metadata, tool concurrency, and stream response shape |
| UI stream consumer | renders parent events and groups nested agent_tool_event values |
| event store | optionally persists parent and child events for replay and debugging |
Requirements
Nested streaming requires:
- the parent run uses
.stream() - specialist tools are created with
stream: true - the child model supports streaming
If nested streaming is unavailable, the specialist still behaves like a normal opaque asTool(...) call. The parent model receives only the final specialist output as the normal tool_result; intermediate child events are for the caller, trace, or event store.
Pages
- Build Streaming Specialists shows how to build specialist agents, expose them with
asTool({ stream: true }), and run the coordinator stream. - Consume Nested Events shows how to group and render parent and child events safely.
- Persistence and Testing covers event-store replay, failure modes, and test coverage.
Choose the Right Shape
| Shape | Use it when |
|---|---|
agent.asTool(...) | child progress can stay hidden |
agent.asTool({ stream: true }) | coordinator decides which specialists to call and the caller should see child progress |
| parallel pipelines | every branch should always run and return typed outputs |
| separate Studio agents | operators should run specialists manually during development |