Skip to main content
Every session runs in one of two decision modes. Intent is the default and the path a real integration uses. Direct is an evaluation baseline. The create response echoes which mode you are in, and because you can omit the mode on create, that echo is how you discover it. Plan for intent.

​
Intent mode

In intent mode the participant forms a free-form intent from perception alone. They say what a human would try, in their own words (“turn the tv on”, “find the checkout button”), carrying no knowledge of your action vocabulary. A separate resolver then maps that intent onto the actions you declared this turn. Splitting the two keeps the participant honest. They reason the way a person does, off what they see, and never off the list of buttons you happen to expose. The resolver, not the participant, does the mapping onto your controls. Resolution comes back three ways:
  • matched: the intent maps to a declared action. action_name and arguments are set; execute it.
  • no_match: the participant wanted something your environment does not offer. action_name is null, and unmet_expectation names the gap. This is usually the signal you are after.
  • none_needed: the participant concluded and named no control. action_name is null and unmet_expectation stays null. This is not a failed mapping; the participant is finishing or stepping away, and the session ends through its own status.
no_match and none_needed both come back with a null action_name, but they mean different things. no_match is a participant who wanted something absent (a finding). none_needed is a participant who is done. Do not treat them alike.

​
The finding channel

Three fields on the decision carry the research signal in intent mode:
  • intent: what the participant wanted, in their words.
  • resolution: whether that intent mapped, and how.
  • unmet_expectation: on a no_match, what the environment did not afford.
A stream of no_match results with their unmet_expectation text is the clearest read you get on where your environment falls short of what a person expects. A participant reaching for something you never built is the point of running one.

​
The experiential payload is always the participant’s

Regardless of mode or resolution, four fields always come straight from the participant: comment, sentiment, felt_intensity, and status. They are present on a matched turn, a no_match turn, and a none_needed turn alike. They are the participant’s in-the-moment experience, not a verdict on whether the task succeeded. Read score outcomes before you trust them as a measure of success.

​
Direct mode

In direct mode the participant picks one of your declared actions themselves, so they see the action list. The intent fields (intent, resolution, unmet_expectation) are all null. Because the participant reads your action vocabulary directly, direct mode is an evaluation baseline, not the product path; the intent split is what makes the behavior a real prediction.

​
Token accounting differs by mode

The two modes count tokens differently, because intent mode runs two model calls (the participant’s intent and the resolver’s mapping):
  • Intent: the per-turn input_tokens is the combined total across both calls, and output_tokens is null by design.
  • Direct: you get the real per-call input and output split.

The decide-only loop

You declare the actions; the resolver maps intent onto them.

Score outcomes

Why the participant’s words are perception, not a verdict.