When to use a session#
| You decide | Use | Why |
|---|---|---|
| Now and then: a ticket, a payment, a tool call | POST /v1/decide | Each decision stands alone; one request, one answer |
| Many inputs at once | Fan-out, or a batch job when it can wait | Parallel requests within your rate limits, or a lower price when it can wait |
| More than 10 times a second, on one evolving input | A session | The context is sent once and stays loaded; each frame carries only what changed |
A decision layer, never the controller#
A vehicle runs in layers. The inner loop keeps it stable, many times a second, on its own controller. Above it sits a layer that decides what to do: continue or abort, which mode, which manoeuvre next. That is the layer a session serves. Its answers feed your controller, which stays in charge of the vehicle.
| Layer | Decides | Runs on |
|---|---|---|
| Mission and planning | The route, the task, the next job | Your planner, with /v1/decide calls when it needs a judgment |
| Decision layer | Which mode now, continue or abort, the next action | A DecisionNode session |
| Inner control loop | Attitude, speed, motors, brakes | Your flight or motion controller, untouched |
The loop#
POST /v1/sessionsinstructions, state, questions, window 8
sent once, billed once
- 1.Open a session once, with the mission brief as
stateand the questions every frame should answer. See Open a session. - 2.On every tick, send only what changed as a frame: telemetry, a sensor reading, a camera frame. See Stream frames.
- 3.Hand each reply to your controller as a request, not a command: it applies the mode when the answer clears your threshold and the controller's own limits allow it.
- 4.When no fresh reply has arrived by your deadline, the controller keeps its current mode or runs its own failsafe. Your code decides that on its own, every time.
- 5.When the socket drops (
1006), the server holding it goes away (1001), it fails on our side (1011), the session expires (4410) or goes idle (4408), open a new session with the same body and carry on. The controller keeps its mode meanwhile. - 6.End the session when the mission ends. See End a session.
Sessions has the complete supervisor in Python and TypeScript: one long-lived task reads your sensor feed, each session streams the newest reading, and a capped backoff reopens sessions after a drop.
Designing frames#
- Put the constant part in the session. The brief, the rules and the geofence go in
stateonce as context; frames carry readings. Enforce the geofence and every flight limit in your flight controller, never through the model. - Keep frames small. A frame holds text or JSON of at most the session's
max_frame_tokens(never more than 4,096 tokens; the open response gives the value), or one image. Name the fields (battery,wind_mps) so the model knows what each value is. - Choose the window for the decision. A mode change that depends on a trend needs a few recent frames; a reflex check on the current frame needs one. Send
"reset": truewhen the situation changes completely, such as after landing. - Ask only what this tick needs. List
questionson a frame to answer some of them; each frame is billed for the questions it asks.
What to build#
- Drones and vehicles, civilian: mission supervision for survey, inspection and delivery flights; return, hold and land decisions; mode selection.
- Simulators and games: the next manoeuvre or action from a stream of state.
- Industrial monitoring: machine state to action, alert or hold, from sensor frames.
- Long-running agents: stream tool results and get a typed next step, without resending the whole context each time.