Skip to main content
Agent framework and tools are currently under development. API details subject to change ahead of general release.
The Questionnaire Interviewing expert enables AI agents to conduct structured interviews and questionnaires, guiding conversations to collect specific information in a systematic manner.
This expert is ideal for patient intake, clinical assessments, and any scenario where structured data collection is required.

​
Capabilities

The Questionnaire Interviewing expert can:
  • Conduct structured interviews following predefined questionnaires
  • Guide conversations to collect specific information
  • Adapt questioning based on responses
  • Ensure comprehensive data collection

​
Use Cases

  • Patient intake and history taking
  • Clinical assessments and screenings
  • Research data collection
  • Structured information gathering workflows

​
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"
  }
}