Streaming (ask)

Start a stream

stream = client.machines.ask(
    machine_id,
    "Report disk usage without changing the machine.",
    pin="1234",
    session="2",
)

const stream = client.machines.ask(
  machineId,
  "Report disk usage without changing the machine.",
  { pin: "1234", session: "2" },
);

PIN is optional when the target does not require one. It must be supplied up front when required.

Frame union

async for frame in stream:
    if frame.type == "event":
        print(frame.payload)
    elif frame.type == "error":
        print(frame.code, frame.message)
    elif frame.type == "done":
        print(frame.success, frame.text)

for await (const frame of stream) {
  if (frame.type === "event") console.log(frame.payload);
  else if (frame.type === "error") console.log(frame.code, frame.message);
  else console.log(frame.success, frame.text);
}

An application-level error frame is followed by done with success=false. Protocol and transport failures reject the stream as typed SDK errors.

error frame codes are stable: machine_offline, no_targets, pin_denied, and internal.

Usage and cost on the done frame

Beyond the result text, the final frame reports what the run consumed — token counts and cost — along with the engine and model that served it, and failure details when the run did not succeed.

All of it is reported only when the provider supplied it, so read it defensively: treat a missing value as unreported rather than as zero.

Collect final text

text = await client.machines.ask(machine_id, "Reply with: pong", pin="1234").collect()

collect() returns the final done text, falling back to accumulated event text. An unsuccessful terminal outcome raises AgentStreamError.