Interface UserInteraction


public interface UserInteraction
Host-supplied surface for pausing the agent's tool-dispatch loop to consult the user. Each method must block the calling thread until the host's UI returns an answer or the user declines. Returning DECLINED (or, for confirmAction(String), returning "no" after a decline) keeps the conversation's tool-call/tool-result pairs balanced so the next send call resumes cleanly.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    Sentinel returned when the user dismisses the question or the host cannot supply an answer.
  • Method Summary

    Modifier and Type
    Method
    Description
    Ask the user a free-form clarifying question and block until they reply.
    askUserChoice(String question, String helperText, List<String> options)
    Ask the user to pick exactly one of options and block until they reply.
    askUserMultiChoice(String question, String helperText, List<String> options)
    Ask the user to pick zero or more of options and block until they reply.
    Ask the user to confirm or decline a proposed action and block until they reply.
  • Field Details

    • DECLINED

      static final String DECLINED
      Sentinel returned when the user dismisses the question or the host cannot supply an answer. The tool description teaches the model to recognize this marker and fall back to reasonable defaults — or to end the turn explaining what it needed.
      See Also:
  • Method Details

    • askFreeformQuestion

      String askFreeformQuestion(String question)
      Ask the user a free-form clarifying question and block until they reply.
      Parameters:
      question - the question to surface, phrased as a complete sentence.
      Returns:
      the user's typed answer verbatim, or DECLINED if they dismissed the prompt.
    • askUserChoice

      String askUserChoice(String question, String helperText, List<String> options)
      Ask the user to pick exactly one of options and block until they reply.
      Parameters:
      question - the question to surface, phrased as a complete sentence.
      helperText - one-sentence context surfaced beneath the question, or empty when no extra framing is helpful — the host renders nothing in that case.
      options - the options to choose between; the host renders one selectable row per option.
      Returns:
      the chosen option string verbatim — either one of the supplied options, or the free-form text the user typed when they picked the "Something else" escape row — or DECLINED if they dismissed the prompt.
    • askUserMultiChoice

      String askUserMultiChoice(String question, String helperText, List<String> options)
      Ask the user to pick zero or more of options and block until they reply.
      Parameters:
      question - the question to surface, phrased as a complete sentence.
      helperText - one-sentence context surfaced beneath the question, or empty.
      options - the options to choose between; the host renders one checkbox row per option.
      Returns:
      a JSON array of the chosen option strings — supplied options the user checked, plus the free-form text from the "Something else" row if the user filled it in — or DECLINED if they dismissed the prompt.
    • confirmAction

      String confirmAction(String prompt)
      Ask the user to confirm or decline a proposed action and block until they reply. Use before taking actions with side effects the user might not expect.
      Parameters:
      prompt - one-sentence description of the action under consideration.
      Returns:
      "yes", "no", or DECLINED if they dismissed the prompt.