Aller au contenu
Base de connaissances

Outils d'enquête — référence des outils MCP

Les outils d’enquête couvrent le cycle d’exécution des enquêtes : création des sessions d’enquête, parcours du déroulé des questionnaires, soumission des réponses et génération de données de test synthétiques. Les items de type commentaire sont ignorés automatiquement : l’appelant ne les reçoit jamais.

Liste les enquêtes, avec un filtre facultatif par questionnaire, campagne, répondant, enquêteur ou statut.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Non — Filtre par identifiant de questionnaire
campaign_id string Non — Filtre par identifiant de campagne
respondent_id string Non — Filtre par identifiant de répondant
interviewer_user_id string Non — Filtre par enquêteur affecté (utilisateur)
status string Non — Filtre : "pending", "in_progress" ou "completed"
expand boolean Non false Renseigne les objets imbriqués questionnaire/enquêteur/répondant/campagne
cursor string Non — Curseur de pagination issu d’une page précédente
limit integer Non 50 Taille de page (100 au maximum)

Renvoie : { data: [...], next_cursor, has_more }, paginé par curseur. Chaque enquête porte status ainsi qu’un booléen dérivé en lecture seule, completed (true exactement lorsque status vaut "completed") ; status est la seule source de vérité, et la surface des enquêtes ne comporte nulle part de filtre ni d’entrée completed.


Met à jour les champs modifiables d’une enquête. Les entités liées (questionnaire, répondant, enquêteur, campagne) sont ici immuables : supprimez et recréez l’enquête pour les relier autrement.

Paramètre Type Obligatoire Par défaut Description
survey_id string Oui — UUID de l’enquête
status string Non — Nouveau statut ; définir "completed" est la manière d’exprimer l’achèvement (il n’existe pas d’entrée completed distincte)
qml_state object Non — Avancé : remplace l’état de déroulé de l’enquête
current_block_id string Non — Avancé : repositionne le pointeur de déroulé
current_item_id string Non — Avancé : repositionne le pointeur de déroulé

Renvoie : l’objet enquête mis à jour (même forme que les entrées de list_surveys, completed dérivé de status).


Crée une nouvelle enquête pour un répondant.

Paramètre Type Obligatoire Par défaut Description
questionnaire_id string Oui — Questionnaire à utiliser
respondent_id string Oui — UUID du répondant
interviewer_user_id string Non — Pour les entretiens par téléphone ou en face à face. À omettre pour l’auto-administration
campaign_id string Non — Associe l’enquête à une campagne

Renvoie : { id, questionnaire_id, interviewer_user_id, respondent_id, campaign_id, mode }

mode est dérivé, jamais défini : field_interview lorsqu’un enquêteur est lié, ai_assisted dès que le répondant a donné son consentement dans son assistant IA avant toute réponse, sinon direct. Tout objet enquête de cette surface le comporte. Voir Mode d’enquête.

Un répondant a au plus une enquête active par campagne. S’il en a déjà une, l’appel est refusé comme conflit (REST 409) en nommant l’identifiant de cette enquête : poursuivez-la, ou supprimez-la d’abord.


Crée des enquêtes pour tous les répondants du vivier affecté à une campagne. Ignore les répondants qui ont déjà une enquête.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne

Renvoie :

{
"status": "success",
"campaign_id": "...",
"created_count": 45,
"skipped_count": 5,
"surveys": [{"id": "...", "respondent_id": "..."}]
}

Prérequis : la campagne doit avoir à la fois un questionnaire et un vivier de répondants affectés.


Renvoie la question courante d’une enquête. Initialise l’état de l’enquête au premier appel.

Paramètre Type Obligatoire Par défaut Description
survey_id string Oui — UUID de l’enquête

Renvoie (question) : l’item courant, ses options de réponse intégrées et le type de contrôle : un seul aller-retour fournit tout ce qu’il faut pour répondre.

{
"survey_id": "...",
"status": "in_progress",
"item": {
"id": "q_gender",
"kind": "Question",
"text": "What is your gender?"
},
"control_type": "radio",
"options": [
{"value": "male", "text": "Male"},
{"value": "female", "text": "Female"},
{"value": "other", "text": "Other"}
],
"required": true
}

Pour un contrôle de type curseur, options contient un descripteur de plage unique :

{"control_type": "slider", "options": [{"type": "range", "min": 18, "max": 99, "step": 1}]}

Les contrôles editbox, range et textarea renvoient une liste options vide ; lisez leurs bornes ou leurs réglages de texte dans le champ input de l’item. Types de contrôle : radio, dropdown, checkbox, slider, switch, editbox, range, textarea.

Renvoie (terminée) : { survey_id, status: "completed", message: "..." }


Soumet une réponse à la question courante et passe à l’item suivant.

Paramètre Type Obligatoire Par défaut Description
survey_id string Oui — UUID de l’enquête
item_id string Oui — Identifiant de l’item auquel vous répondez
outcome any Oui — Valeur de la réponse (son type dépend du contrôle ; une réponse Range est une paire [low, high])

Renvoie :

{
"survey_id": "...",
"status": "in_progress",
"output": { },
"next": { }
}

status vaut "in_progress" ou "completed". next intègre l’étape suivante (même forme que get_survey_current_item), ce qui évite une récupération séparée ; il vaut null une fois l’enquête terminée. Les items de type commentaire qui suivent sont traités automatiquement après chaque soumission.


Marque explicitement une enquête comme terminée. À utiliser dans les cas limites où l’achèvement automatique ne se déclenche pas.

Paramètre Type Obligatoire Par défaut Description
survey_id string Oui — UUID de l’enquête

Renvoie : { status: "success" | "already_complete", survey_id, message }.


Met en file d’attente une tâche asynchrone d’arrière-plan qui remplit toutes les enquêtes en attente d’une campagne avec des réponses de test synthétiques. À ne pas utiliser sur des campagnes contenant des données réelles de répondants.

L’outil renvoie immédiatement un task_id ; la boucle de génération s’exécute comme tâche d’arrière-plan sur le worker propre à Portor. Interrogez get_task_status jusqu’à ce que la tâche atteigne un état final : completed (toutes les enquêtes remplies), partial (certaines enquêtes remplies, d’autres en échec, par exemple à cause de données de répondant erronées ou d’une erreur QML passagère) ou failed (aucune enquête remplie : soit une erreur de validation préalable comme une campagne absente, soit l’échec de toutes les enquêtes de l’exécution ; last_error en donne la raison). Les trois états s’excluent mutuellement : tout mélange de réussites et d’échecs aboutit à partial, jamais à failed.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne
distribution string Non "realistic" Stratégie : "realistic", "random" ou "llm" ; toute autre valeur est refusée
max_surveys integer Non — Limite le nombre d’enquêtes à remplir. null = toutes celles en attente
profiles string[] Non ["random"] Profils de persona, attribués à tour de rôle
concurrency integer Non 1 Taille du pool de threads par tâche pour la boucle interne
Distribution Choix des réponses À utiliser pour
realistic Pondéré par les données démographiques et le profil de persona du répondant : les questions à choix utilisent des poids qui dépendent du profil, les curseurs une loi gaussienne, les saisies de texte des formulations propres au profil Tests du pipeline à fort volume (rapide)
random Uniforme, sans influence démographique Tests de charge (le plus rapide)
llm Un appel à Claude Haiku par question, avec le persona, les données démographiques du répondant et toutes ses réponses précédentes dans l’enquête, pour que l’enquête reste cohérente avec elle-même. Environ une seconde par question Réponses ouvertes plausibles ; nécessite des identifiants IA dans votre profil

Profils : young_single, married_family, retired, high_income, random.

Renvoie (de manière synchrone, après la validation de mise en file d’attente) :

{
"task_id": "f5b6c7d8-...",
"status": "pending",
"campaign_id": "...",
"distribution": "realistic",
"profiles": ["young_single", "retired"]
}

Interrogez get_task_status(task_id) jusqu’à ce que state vaille completed, partial ou failed. status_text affiche la progression en direct (par exemple "47 of 200 surveys processed") et, dans un état final, un bilan du remplissage (par exemple "47 of 200 surveys filled (3 failed)") ; last_error contient un motif expurgé en cas d’échec. Pour réessayer après un résultat partial, relancez mass_fill_surveys sur la même campagne : le remplissage ne traite que les enquêtes qui ne sont pas encore terminées, les enquêtes déjà remplies sont donc ignorées.

Mode Moteur Vitesse Description
realistic Aléatoire pondéré Rapide Pondération démographique tenant compte du profil (par défaut)
random Aléatoire uniforme Rapide Purement aléatoire, sans influence démographique
llm API Claude Haiku ~1 s/question Réponses générées par l’IA, cohérentes avec le persona. Nécessite que votre fournisseur de raisonnement (ou celui de votre organisation) soit Anthropic API ou AWS Bedrock, avec ses identifiants enregistrés

Attribués à tour de rôle aux répondants. Profils disponibles :

Profil Âge Revenu Comportement
young_single 25–35 65 000 $ Progressiste, à l’aise avec la technologie, privilégie les options intermédiaires
married_family 30–50 80 000 $ Pragmatique, attentif au rapport qualité-prix
retired 65+ 55 000 $ Conservateur, privilégie les premières options ou les options traditionnelles
high_income 45 150 000 $ et plus Attaché à la qualité, privilégie les options haut de gamme
random 40 70 000 $ Aucun biais particulier

Les réponses sont des codes numériques (les labels d’un contrôle à choix associent des codes entiers à des libellés affichés ; c’est le code qui est soumis), et du texte libre uniquement pour le contrôle textarea. Voir Format de présentation des enquêtes pour le contrat complet.

Type d’item Format de la réponse Exemple
Comment null (ignoré automatiquement) Texte informatif
Question Un seul nombre : code de réponse / valeur numérique / interrupteur 1-0 (Checkbox : entier en masque de bits ; Textarea : chaîne) 2, 42, true
QuestionGroup Liste de nombres, un par sous-question, tous issus du contrôle unique partagé par le groupe [1, 3, 2]
MatrixQuestion Liste imbriquée de nombres, lignes × colonnes, avec un contrôle partagé [[1, 2], [3, 1]]

Supprime plusieurs enquêtes selon des critères de filtre. Suit une procédure en deux étapes : appelez d’abord avec dry_run=true pour prévisualiser ce qui sera supprimé, puis appelez à nouveau avec dry_run=false pour exécuter.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — Supprime les enquêtes de cette campagne
status string Non — Ne cible que les enquêtes ayant ce statut : "pending", "in_progress" ou "completed"
dry_run boolean Non true Mode aperçu : renvoie le nombre et un échantillon sans rien supprimer

Renvoie en mode aperçu :

{
"dry_run": true,
"count": 25,
"sample": [{"id": "...", "respondent_id": "...", "status": "pending", "campaign_id": "..."}],
"message": "Would delete 25 surveys. Call again with dry_run=False to execute."
}

Renvoie à l’exécution : { dry_run: false, deleted: 25 }


Situation Réponse
Enquête introuvable {"error": "Survey {id} not found"}
Campagne introuvable {"error": "Campaign {id} not found"}
Questionnaire introuvable {"error": "Questionnaire {id} not found"}
Enquête non initialisée {"error": "Survey not initialized. Call get_survey_current_item first."}
Aucun vivier affecté {"error": "Campaign has no respondent pool assigned"}
Aucune enquête inachevée {"status": "no_surveys", "message": "No incomplete surveys found in campaign"}
[Not Started] → get_survey_current_item → [In Progress]
[In Progress] → submit_survey_response → [In Progress | Completed]
[In Progress] → finish_survey → [Completed]
  • Initialisation : le premier appel à get_survey_current_item charge le QML et crée l’état de l’enquête
  • Achèvement automatique : les enquêtes se terminent automatiquement lorsque le dernier item reçoit une réponse
  • Commentaires ignorés : les items de type commentaire sont traités de manière transparente (jusqu’à 50 consécutifs) ; l’appelant ne les reçoit jamais
  • Persistance : chaque réponse est immédiatement enregistrée dans la base de données