Skip to main content
Kviria keeps no conversation between calls. Each response carries a state string instead, and your agent sends it back on the next call. That string is the whole conversation as Kviria needs it. Carry the state gives the steps.

​
What it holds

The state holds:
  • the user’s position;
  • the places Kviria just listed, up to 5;
  • the place waiting for a yes or no;
  • the places settled earlier, up to 5, the most recent first;
  • the street being discussed.
That is how “the second one”, “yes” and “what’s across from it” find their place. The string is at most 2,263 characters. In practice it is far shorter: the states in the Quickstart are 71 to 94 characters.

​
It is signed, not encrypted

  • Kviria signs the state. A state that was changed, cut short or made up is refused with 400 invalid_state and an empty state, and the conversation starts again.
  • The state is not encrypted. It carries the user’s position and the ids of places. If your platform logs tool calls, it logs the position in the state as well as in the request.

​
The position

The first call’s anchor goes into the state. A later call that sends anchor replaces it, because the user has moved. A call without one uses the position in the state. One exception: a sent position that is the coordinate of a place, a door or a street corner from the area (within 0.1 m) is not taken as the user’s. Agents sometimes copy a coordinate from an answer into anchor, and that would move the search onto that place. Kviria keeps the earlier position instead, and the answer’s evidence ends with an anchor_is_area_point entry.

​
Turns that find nothing new

When a turn runs no search, its response returns the state you sent, with the position updated. That happens on a request too vague to search (unclear), on a kind of place the area has none of (none) and on a position outside coverage. The conversation then carries on from where it was.

​
Why a state string

You hold the conversation: nothing about it is kept on Kviria’s side between your calls. A lost response can be retried by sending the same request again, with the same state. And any of your agent’s instances can continue a conversation from the state it receives.