Questionnaire

1. Purpose

The Questionnaire component runs one preset-backed questionnaire as a multi-turn conversation. It manages conversational state for PHQ-9, GAD-7, BMI, AUDIT-C, AUDIT, and WHO-5, resumes the active questionnaire automatically from the current flow session when available, returns the next question to ask, and emits a structured state payload or final deterministic score result for downstream logic.

Use this component when a flow needs deterministic questionnaire collection, screening, or calculator-style input capture. It works best when one flow instance handles one questionnaire preset at a time.

2. Inputs

Input: Preset

• Type: Dropdown/List
• Description: Selects which questionnaire preset drives the conversation. Supported presets are fixed and available in the component UI.
• Supported presets:
  • PHQ-9
  • GAD-7
  • BMI
  • AUDIT-C
  • AUDIT
  • WHO-5
• One component instance handles one active questionnaire preset at a time. The selected preset controls the question order, prompts, allowed response options, validation rules, and scoring behavior.

Input: Latest Answer

• Type: Message Text
• Description: Holds the user's latest answer for the current question.
• This input is exposed in tool mode so an Agent can pass the normalized answer for the current prompt. Leave it empty to start a fresh questionnaire session or to inspect the current state without advancing. On follow-up turns, pass the canonical answer label/value or numeric value that clearly matches the current question.
• Invalid answers do not advance the questionnaire. The component stays on the same question and returns validation details.

3. Outputs

Output: Questionnaire Result

• Type: Data
• Description: Returns the questionnaire result as structured data plus a short summary text.
• The payload typically includes:
  • questionnaire status (in_progress, complete, invalid, or unsupported)
  • questionnaire identity and preset metadata
  • current question metadata
  • state token for continuation
  • raw answers and normalized answers
  • completion status
  • missing or invalid field details
  • scoring metadata when the preset defines scoring
  • score, raw score, normalized percent, interpretation, and threshold flags when complete
• The output is the single source of truth for the next step in the flow. Downstream components should inspect the returned structured data rather than trying to infer questionnaire progress from chat history.

4. Configuration

Tool Mode

The Questionnaire component is tool-only. It is connected to an Agent so the Agent can manage the conversational questionnaire loop. In this setup, the Agent gets access to the questionnaire's tool-visible answer input and decides when to call the component on each user turn.

This setup is useful when questionnaire collection is part of a broader conversation, such as an intake assistant, mental-health screening assistant, or coaching flow. The Agent should send one answer at a time, using the latest Questionnaire result to determine the next prompt and whether the questionnaire is complete.

Example:

5. Example Usage

This component is commonly used in a screening or intake flow:

Chat Input -> Agent -> Questionnaire -> Chat Output

In this setup, Questionnaire is connected to the Agent in tool mode. The Agent handles the conversation, keeps the questionnaire moving, and returns structured results when the preset is complete.

What the user should provide:

• A request to create or use an agent for a questionnaire
• The questionnaire topic or screening goal
• Optional context such as screening purpose, user age group, or follow-up workflow

The user does not need to know the preset internals, field ids, or state token shape. A natural-language request is usually enough.

Example test input:

Start a PHQ-9 questionnaire and keep asking me one question at a time.

Another example:

Create an agent to fill a general anxiety form.

Expected behavior:

The Agent should use the selected preset, manage the questionnaire loop, and return a structured result when the preset is complete. The flow should stay focused on the selected questionnaire and preserve state between turns.

For scoring presets, the final result should be treated as structured screening data, not as a diagnosis or treatment plan.

6. Notes / Best Practices

• Use tool mode when Questionnaire is part of a broader conversation handled by an Agent. The Agent should validate user replies, preserve turn-by-turn state, and keep asking one question at a time.

• Connect the questionnaire state through the current flow session whenever possible. The component can resume automatically from the active runtime session, so most flows do not need to manage state manually.

• Use exact answer mapping. Choice questions expect a clear match to one allowed option, and numeric questions expect a valid numeric value within the defined range.

• Keep one node on one preset. If you need a different questionnaire, use a separate Questionnaire component instance.

• Expect scoring only when the preset defines it. Complete questionnaire presets return a final score and interpretation; incomplete or invalid turns return the next question or validation feedback instead.

• For Agent prompts, be explicit: ask one question at a time, normalize only when the answer is unambiguous, do not advance from memory alone, and stop when the component returns complete.