session created through the quickstart. They are independent alternatives: do not send every example for the same question. Choice labels are illustrative; use those of your question.
Open question
Send the person’s actual words.- Python
- TypeScript
Choice question
Use the exact labels returned by the pending question. Send one label for single choice, and several only if multiple choices are allowed.- Python
- TypeScript
Semi-open question
Choices alone are sufficient. If the person adds an explanation, send it infree_text / freeText. A free-text “other” answer alone is also possible.
- Python
- TypeScript
No answer or refusal
These outcomes need no text. Do not use them as a substitute for an actual answer.- Python
- TypeScript
Context received outside the exchange
apply_events / applyEvents updates state without consuming a turn. The engine may analyze this text. The pending decision is then recomputed: see When the pending question changes.
- Python
- TypeScript
Already-known data
Use the stable identifier of the information configured in your domain, not an invented ID. Here,available_budget must exist in the published version. Confirmed structured data needs no text analysis.
- Python
- TypeScript
What the SDK handles
Foranswer(...), it associates the answer with the pending decision and resolves choice labels. Answering an open question without text is rejected locally, before any network call. It then returns the next decision, not just an acknowledgement.
Choices alone and no-answer outcomes need no model call, provided no other text requiring analysis is supplied. Free text is analyzed by the engine: do not routinely copy a choice label into user_text.
When the pending question changes
Afterapply_events / applyEvents, the pending decision is recomputed on the updated state, with the selection constraints of the call that proposed it. This step calls no model and consumes no turn.
- If the same candidates remain the most useful, the decision and its
decision_idare unchanged. - Otherwise,
pending_decisioncarries a new decision with a newdecision_id. Supplying the information that the pending question asked for is the common case: that question is withdrawn. - If no question is left, the session stops (
status: "stopped"). If only the selection constraints of the original call leave no question,pending_decisionisnull, the session stays active, and the nextnext()call chooses.
answer(...) attaches the next reply to it.
If your application had already shown the replaced question and the person answers it, do not send that reply with answer(...), which always targets the pending decision: send it as context with apply_events / applyEvents. Through the REST API, a previous_turn that cites the replaced decision_id is accepted once by /next: the reply goes to that question if it is still a candidate; otherwise it is read as context, without recording an answer for the withdrawn question or consuming a turn. See Manage a conversation.