Skip to main content

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.

[
  {
    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.
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.

​
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)

​
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): 
{
  "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 
{
    "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: 
{
  "message": {
    "role": "user",
    "kind": "message",
    "messageId": {generateUUID()},
    "contextId": "<context_123>",
    "parts": [
      {
        "kind": "text",
        "text": "I had 7 hours of sleep"
      }
    ]
  }
}
Agent response 
{
    "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: 
{
  "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): 
{
  "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"
  }
}