Route the next
agent action.

QUESTION DESIGN

Make every outcome operational.

{
  "next_action": {
    "type": "choice",
    "instructions": "Choose the safest useful next action",
    "criteria": {
      "search": "Fresh external facts are required",
      "code": "A scoped implementation step is ready",
      "ask_user": "A missing choice changes the result",
      "stop": "The goal is complete or action is unsafe"
    }
  }
}

Good criteria describe what each option means in the workflow. Avoid overlapping labels and do not hide permissions or business rules inside model instructions. The request shape follows the documented question types.

REQUEST AND RESPONSE

One state, one routing decision.

The state is a compact object, not a transcript. It carries the goal, the last result, and the budget left, which is enough to choose among four legal actions.

{
  "model": "jev-latest",
  "state": {
    "goal": "Fix the failing login test",
    "last_result": "Test fails: token expired in fixture",
    "budget_steps_left": 3
  },
  "questions": {
    "next_action": {
      "type": "choice",
      "instructions": "Choose the safest useful next action",
      "criteria": {
        "search": "Fresh external facts are required",
        "code": "A scoped implementation step is ready",
        "ask_user": "A missing choice changes the result",
        "stop": "The goal is complete or action is unsafe"
      }
    }
  }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "next_action": {
      "type": "choice",
      "choice": "code",
      "probabilities": { "search": 0.04, "code": 0.86, "ask_user": 0.08, "stop": 0.02 },
      "confidence": 0.86
    }
  },
  "usage": { "input_tokens": 212, "output_tokens": 12 }
}

Label: illustrative. The field names follow the documented API; the values are invented to show branching, not measured results.

THRESHOLD BANDS

Turn the distribution into a policy.

These bands are starting points, not recommendations for your workload. Calibrate the cutoffs on labeled examples from your own agent, and use stricter bands for irreversible actions than for a read-only search.

IMPLEMENTATION

From model answer to safe action.

1. Keep the option set small. Use outcomes that map directly to code paths, and include an explicit “stop” or “none applies” option so the model is never forced into a wrong route.
2. Set a confidence gate. When the top probabilities are close, ask for review instead of guessing.
3. Validate permissions. The selected action still passes deterministic authorization checks. Selection is not authorization.
4. Choose arguments elsewhere. Jev picks the tool; code or an LLM fills in the arguments, because Jev returns one of your declared options rather than free text.
5. Log outcomes. Store the state, probabilities, chosen path, and real task completion together, then tune thresholds against the record.

FAILURE MODES

What goes wrong in practice.

• Overlapping labels. If “search” and “ask_user” can both be right, the probability splits and no threshold works. Rewrite the descriptions until each option is distinct.
• No escape option. Without “stop” or “none applies”, an unsafe or finished state still has to pick something.
• Stale or bloated state. Old tool output crowds the 32k-token budget and dilutes the signal. Summarize history and send only what the next step needs.
• Non-English state. English is where documented accuracy is best, so validate thresholds separately for other languages.
• Treating routing as safety. A high probability for “code” does not mean the code change is allowed. Guard risky actions separately.

WHEN NOT TO USE JEV

Cases where another tool is a better fit.

• Only one route is ever legal. Use plain code.
• The next step needs a written plan or generated arguments. Use an LLM for that step and Jev only to gate it.
• You have more than 255 candidate actions. Split them into a hierarchy of smaller Choice questions.
• The decision must replay identically from the same input. Use deterministic rules.