Skip to main content
Streaming lets you show a run’s progress while the agent works, for example a “searching the knowledge base” line in your own chat window, instead of waiting for the final answer. There are two streams: Closing either stream never cancels the run. The run finishes, its result is saved and it is billed once. To stop it, cancel it.

The chat stream

-N turns off curl’s buffering so lines show as they arrive. The response is application/x-ndjson and carries the header x-agent-run-id: <run_id>. Keep that id: if the connection drops, you can poll, stream or cancel the run with it. Authentication, validation and limit errors come back as a normal JSON error response before the stream starts. See Errors.

Lines on the chat stream

Read the body line by line and parse each line as JSON. A line is one of these:

Read the chat stream in Python

Turn off the read timeout, or set it high. A run can be quiet for a while before its first progress line, while it waits to start or works on a long step.

The run stream

GET /runs/{run_id}/stream sends Server-Sent Events over the run’s life. It needs the same access as polling the run.
Each event has an id, an event name and a JSON data line:
A comment line (: heartbeat) arrives about every 15 seconds to keep proxies from closing the connection.

Reconnecting

Reconnect whenever the stream closes before done. Every connection starts with a fresh init snapshot that replaces what you had, so nothing is lost in between. Last-Event-ID (or the last_event_id query parameter) is accepted to keep event ids increasing, but it does not replay missed events. Access is checked again every minute while the stream is open, so a key that is turned off mid-run gets a stream_error within about a minute.