Runtime Stream and Side-channel Output

Visualization boundary: the runtime stream diagram explains side-channel observability, not flow-config export.

runtime_stream is a side-channel output, not business state and not the final result.

1. Runtime stream pipeline

How to read this diagram

• runtime_stream exists alongside state and result; it is not an alias for either.
• Its value is observability of intermediate states, not recoverable business state.
• child-flow stream events can now also be bridged back into the parent execution stream.

2. Public APIs

• data.put_into_stream(...)
• data.async_put_into_stream(...)
• data.stop_stream()
• data.async_stop_stream()
• flow.get_runtime_stream(...)
• flow.get_async_runtime_stream(...)
• execution.get_runtime_stream(...)
• execution.get_async_runtime_stream(...)

3. Basic example

from agently import TriggerFlow, TriggerFlowRuntimeData

flow = TriggerFlow()

@flow.chunk("stream_steps")
async def stream_steps(data: TriggerFlowRuntimeData):
    data.put_into_stream({"step": 1})
    data.put_into_stream({"step": 2})
    data.stop_stream()
    return "done"

flow.to(stream_steps)

for event in flow.get_runtime_stream("start", timeout=None):
    print(event)

4. sub_flow bridges child stream by default

Starting in v4.0.8.3, if the parent flow calls:

flow.to_sub_flow(child_flow)

then the child's:

• put_into_stream(...)
• async_put_into_stream(...)

events are forwarded into the parent execution runtime stream by default.

That means a UI or log consumer can observe the full parent-child execution chain from a single parent stream.

5. Interrupts also go into the stream

When execution enters:

• pause_for()
• continue_with()

the runtime stream emits structured interrupt events.

That allows a UI to consume the stream directly instead of polling internal state.

6. Timeout semantics

If no new event arrives for too long, get_runtime_stream(timeout=...) stops and emits a warning.

This does not stop the execution itself. It only stops stream consumption.

7. Recommended usage

• use the stream for intermediate-state display
• use state for recoverable data
• use result for the final business output
• use write_back for explicit parent-child result transfer

8. Boundaries you should not mix up

• stream is not write_back
• stream is not state
• stream bridging only improves observability; it does not synchronize parent and child state