Summary
v1 of subagent-as-tool (#165, PR #173) ships with buffered subagent execution: the
parent waits for the subagent to finish and emits a single tool result. v2 streams
the subagent's events as nested SubagentDelta events on the parent's stream so
the UI can render delegation in real time.
The forward-compat plumbing already exists. PR #173 reserved a SubagentDelta
StreamEvent variant with no emitter; this issue is to wire it up end-to-end.
What lands
SubagentTransport.execute_streaming() (or equivalent) returns an async
iterator of child StreamEvents instead of a buffered SubagentResult
- The
delegate_to_agent tool re-emits child events as
SubagentDelta(agent_name, delta) on the parent's stream
- The parent's
astep_stream consumer treats SubagentDelta as informational
(does not feed it back to the model)
- Cost roll-up still happens at completion —
_persist_cost_data continues to
drain _subagent_token_usage once the subagent finishes
- UI rendering coordinated with
fips-agents/ui-template (separate issue there)
Open design questions
- Backpressure / dropping. If the parent's consumer is slow and the
subagent is fast, do we buffer, drop, or apply backpressure? Design doc
suggests a SubagentDeltaDropped warning event; pick one and document it.
- Mid-stream subagent failure. When the subagent crashes after emitting
partial deltas, what does the parent see? Likely a terminal SubagentFailed
following the partial deltas, but spec the contract.
- Nested delegation. A subagent that itself delegates — do we flatten the
delta stream or wrap it twice? Flattening with agent_name chains is
probably right; verify against trace structure.
Out of scope
- kagenti-driven discovery (separate issue)
- Remote-side depth enforcement (separate issue)
Dependencies
- Requires UI work in
fips-agents/ui-template to render delegation visibly.
Related
Summary
v1 of subagent-as-tool (#165, PR #173) ships with buffered subagent execution: the
parent waits for the subagent to finish and emits a single tool result. v2 streams
the subagent's events as nested
SubagentDeltaevents on the parent's stream sothe UI can render delegation in real time.
The forward-compat plumbing already exists. PR #173 reserved a
SubagentDeltaStreamEvent variant with no emitter; this issue is to wire it up end-to-end.
What lands
SubagentTransport.execute_streaming()(or equivalent) returns an asynciterator of child
StreamEvents instead of a bufferedSubagentResultdelegate_to_agenttool re-emits child events asSubagentDelta(agent_name, delta)on the parent's streamastep_streamconsumer treatsSubagentDeltaas informational(does not feed it back to the model)
_persist_cost_datacontinues todrain
_subagent_token_usageonce the subagent finishesfips-agents/ui-template(separate issue there)Open design questions
subagent is fast, do we buffer, drop, or apply backpressure? Design doc
suggests a
SubagentDeltaDroppedwarning event; pick one and document it.partial deltas, what does the parent see? Likely a terminal
SubagentFailedfollowing the partial deltas, but spec the contract.
delta stream or wrap it twice? Flattening with
agent_namechains isprobably right; verify against trace structure.
Out of scope
Dependencies
fips-agents/ui-templateto render delegation visibly.Related
planning/subagent-tool-design.md("Streaming roadmap" section)