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.
list_surveys
Section intitulée « list_surveys »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.
update_survey
Section intitulée « update_survey »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).
create_survey
Section intitulée « create_survey »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.
bulk_create_surveys
Section intitulée « bulk_create_surveys »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.
get_survey_current_item
Section intitulée « get_survey_current_item »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: "..." }
submit_survey_response
Section intitulée « submit_survey_response »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.
finish_survey
Section intitulée « finish_survey »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 }.
mass_fill_surveys
Section intitulée « mass_fill_surveys »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.
Modes de distribution
Section intitulée « Modes de distribution »| 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 |
Profils de persona
Section intitulée « Profils de persona »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 |
Traitement selon le type d’item
Section intitulée « Traitement selon le type d’item »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]] |
bulk_delete_surveys
Section intitulée « bulk_delete_surveys »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 }
Gestion des erreurs
Section intitulée « Gestion des erreurs »Erreurs courantes
Section intitulée « Erreurs courantes »| 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"} |
Machine à états des enquêtes
Section intitulée « Machine à états des enquêtes »[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_itemcharge 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