> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corti.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Interviewing

> Guide users through structured questionnaires and clinical interviews step by step

```json theme={null}
[
  {
    name: "interviewing-expert",
    type: "reference",
  }
]
```

The **Interviewing** expert manages questionnaire-style interviews with the user. Use this expert whenever the user is answering or progressing through a questionnaire — always pass the questionnaire `data_part` (and its ID) when available so the expert can follow the correct structure and logic.

<Tip>
  When invoking this expert, set the `text` argument to the raw content of what the user just said or answered, with no extra commentary, prompts, or instructions.
</Tip>

## Capabilities

The Interviewing expert can:

* Drive structured interviews that follow a provided questionnaire definition
* Guide the conversation question-by-question and adapt based on responses
* Track answers and resolve conditional flow (`next`, `defaultNext`, `conditions`)
* Return structured `questionnaire_response` artifacts the orchestrator can consume

## Use cases

* Patient intake and history-taking
* Clinical assessments and screening questionnaires
* Research and survey data collection
* Any structured, multi-step information-gathering workflow

## Documentation

### Questionnaire

* `questionnaireId`: `string` (required)
* `version`: `string | number` (required)
* `startQuestion` : `string` (required, but will be optional soon; ID of a question)
* `questions`: `Question[]` – list of unique IDs (required)
* `title`, `description`, `meta`: optional

### Question (Discriminated by `type`)

Common fields for **all** question types:

* `id`: `string` (required, unique)
* `type`: one of the literals below (required)
  * `boolean`
  * `text_short`
  * `text_long`
  * `number`
  * `date_time` (with `mode`: `date` | `time` | `datetime`)
  * `scale` (with `min`, `max`, optional `step`, optional `labels[]`)
  * `single_choice` (with `options[]`)
  * `multi_choice` (with `options[]`, optional `maxSelections`)
* `text`: `string` (required)
* `guideline`: `string` (optional, instructs model to provide guidelines to the end user, can be used to augment question text)
* `facets`: `string` (optional, hints for the LLM on how to populate and interpret user answers)
* `required`: `boolean` (optional; if `true`, agent must collect a valid answer)
* `conditions`: `Condition[]` (optional; controls visibility/flow)
* `defaultNext`: `string` (optional; ID of the next question if no option-level `next` applies)
* `meta`: `object` (optional)

<aside>
  📌

  Example `date_time`

  ```json theme={null}
  {
    "id": "question-1",
    "type": "date_time",
    "mode": "date", // "date", "time", or "datetime"
    "text": "When did you go to bed?"
  }
  ```
</aside>

<aside>
  📌

  Example `single_choice`

  Used for radio-style single selections

  ```json theme={null}
  {
    "id": "question-2",
    "type": "single_choice",
    "text": "How often do you exercise?",
    "options": [
      {"value": "daily", "label": "Daily", "next": "question-4"},
      {"value": "weekly", "label": "Weekly"},
      {"value": "rarely", "label": "Rarely"}
    ]
  } 
  ```

  **Note**:  `multi_choice` is similar but allows multiple selections
</aside>

### Options (for choice questions)

* `value`: `string | number | boolean`
* `label`: `string`
* `guideline`: `string` (optional)
* `next`: `string` (optional, overrides `defaultNext` when chosen)

### Conditions

**Operators:** `=`, `!=`, `<`, `<=`, `>`, `>=`, `contains`, `not_contains`, `in`, `not_in`, `exists`, `not_exists`

* `question`: `string` – the **source** question ID to evaluate
* `operator`: as above
* `value`: required for all operators **except** `exists`/`not_exists`

## Example requests

### 1. Initial Request

User provides an incomplete or ambiguous answer (starts the flow):

```json theme={null}
{
  "message": {
    "role": "user",
    "kind": "message",
    "messageId": {generateUUID()},
    "parts": [
      {
        "kind": "text",
        "text": "Answer to the questionnaire: I'm ok satisfied"
      },
      {
        "kind": "data",
        "data": {
          "type": "questionnaire",
          "questionnaire": {
            "questionnaireId": "sleep-survey-v1",
            "version": "1.0",
            "startQuestion": "question-1",
            "questions": [
              {
                "id": "question-1",
                "type": "scale",
                "text": "How satisfied are you?",
                "min": 1,
                "max": 5
              },
              {
                "id": "question-2",
                "type": "scale",
                "text": "How many hours of sleep did you have?",
                "min": 0,
                "max": 12
              },
              {
                "id": "question-3",
                "type": "text_short",
                "text": "How well rested do you feel?"
              },
              {
                "id": "question-4",
                "type": "single_choice",
                "text": "How many interruptions did you have?",
                "options": [
                  {"value": "none", "label": "None at all"},
                  {"value": "few", "label": "A few"},
                  {"value": "lots", "label": "Lots"}
                ]
              }
            ]
          }
        }
      }
    ]
  }
}
```

**Agent response**

```json theme={null}
{
    "task": {
        "id": "<task_id>",
        "contextId": "<context_123>",
        "status": {
            "state": "completed",
            "message": {
                "role": "agent",
                "parts": [
                    {
                        "kind": "text",
                        "text": "Thanks, how many hours of sleep did you have?"
                    }
                ],
                "messageId": "<message_id>", // For client use to track messages
                "taskId": "<task_id>",
                "contextId": "<context_123>",
                "kind": "message"
            }
        },
        "artifacts": [{
            "artifactId": "<artifact_id>",
            "parts": [
                {
                    "kind": "data",
                    "data": {
                        "answers": {
                            "question-1": 3
                        },
                        "is_completed": false,
                        "next_question_id": "question-2",
                        "questionnaire_id": "sleep-survey-v1",
                        "version": "1.0"
                    },
                    "metadata": {
                        "type": "questionnaire_response"
                    }
                }
            ]
        }],
        "history": [
	        // ...
	      ],
        "metadata": {
            // contains metadata related to task execution
            // not relevant for purposes of input/output
        },
        "kind": "task"
    }
}
```

### 2. Second Request

User clarifies and completes the missing information:

```json theme={null}
{
  "message": {
    "role": "user",
    "kind": "message",
    "messageId": {generateUUID()},
    "contextId": "<context_123>",
    "parts": [
      {
        "kind": "text",
        "text": "I had 7 hours of sleep"
      }
    ]
  }
}

```

Agent response

```json theme={null}
{
    "task": {
        "id": "<task_id>",
        "contextId": "<context_123>",
        "status": {
            "state": "completed",
            "message": {
                "role": "agent",
                "parts": [
                    {
                        "kind": "text",
                        "text": "Thanks, how many interruptions did you have while sleeping?"
                    }
                ],
                "messageId": "<message_id>", // For client use to track messages
                "taskId": "<task_id>",
                "contextId": "<context_123>",
                "kind": "message"
            }
        },
		    "artifacts": [{
				   "artifactId": "<artifact_id>",
			     "parts": [
		     		 {
			        "kind": "data",
			        "data": {
					      "answers": {
					        "question-1": 3,
					        "question-2": 7
					      },
					      "is_completed": false,
					      "next_question_id": "question-3",
					      "questionnaire_id": "sleep-survey-v1",
			          "version": "1.0"
				      },
				      "metadata": {
					      "type": "questionnaire_response",
				      }
					   }
					 ]
		    }],
        "history": [
            // ...
        ],
        "metadata": {
            // contains metadata related to task execution
            // not relevant for purposes of input/output
        },
        "kind": "task"
    }
}
```

### 3. Final Request

User clarifies and completes the missing information:

```json theme={null}
{
  "message": {
    "role": "user",
    "kind": "message",
    "messageId": {generateUUID()},
    "contextId": "<context_123>",
    "parts": [
      {
        "kind": "text",
        "text": "I feel well rested and was not interrupted"
      }
    ]
  }
}

```

**Agent response (final result):**

```json theme={null}
{
  "task": {
    "id": "<task_id>",
    "contextId": "<context_123>",
    "status": {
      "state": "completed"
    },
    "artifacts": [{
      "artifactId": "<artifact_id>",
      "parts": [
        {
          "kind": "data",
          "data": {
            "type": "questionnaire_response",
            "answers": {
              "question-1": 3,
              "question-2": 7,
              "question-3": "Well rested",
              "question-4": "none"
            },
            "is_completed": true,
            "next_question_id": null,
            "questionnaire_id": "sleep-survey-v1",
            "version": "1.0"
          },
          "metadata": {
            "type": "questionnaire_response"
          }
        }
      ]
    }],
    "history": [
      //...
    ],
    "metadata": {},
    "kind": "task"
  }
}

```