Streaming
Some things are long-running — a launch, an agent session, a playbook run — and polling them is both slower and noisier than being told.
When to stream and when to poll
| You want | Do this |
|---|---|
| Live session output as the agent works | Stream |
| Launch progress through its phases | Stream, or poll the instance |
| "Is it ready yet" in a script that does one thing | Poll — it is simpler, and a script that does one thing does not need a stream |
| An audit of what happened after the fact | Read the stored session events; they persist |
Session and run streams
Live agent output is delivered as Server-Sent Events. A stream carries a monotonically increasing sequence number on every event, so a consumer can tell whether it missed anything and where to resume from. Every run ends with a terminal event carrying its outcome — a stream that simply stops is a disconnection, not a finished run. Treat the two differently.
What a stream does not change
A stream is a faster way to learn the same facts, not a different source of truth. In particular, readiness is still read the same way — and it is the thing most often read wrongly. → Knowing when a runtime is ready
The controller's connection is not an integration surface
Your controller holds its own connection to PlatformSmith. That is how launches reach your infrastructure, and it is not something you build against. It matters to you for one reason: it is outbound only, which is why your network needs no inbound path.