Kitöltési eszközök – MCP-eszközreferencia
A kitöltési eszközök a kérdőívkitöltés életciklusát kezelik: kitöltési munkamenetek létrehozása, a kérdőív menetének bejárása, válaszok beküldése és szintetikus tesztadatok generálása. A megjegyzéselemeket a rendszer automatikusan átugorja – a hívó soha nem kapja meg őket.
list_surveys
Szekció neve “list_surveys”Kitöltések listázása, igény szerint kérdőív, kampány, válaszadó, kérdező vagy állapot szerint szűrve.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Nem | — | Szűrés kérdőív-azonosító szerint |
campaign_id |
string |
Nem | — | Szűrés kampányazonosító szerint |
respondent_id |
string |
Nem | — | Szűrés válaszadó-azonosító szerint |
interviewer_user_id |
string |
Nem | — | Szűrés hozzárendelt kérdező (felhasználó) szerint |
status |
string |
Nem | — | Szűrés: "pending", "in_progress" vagy "completed" |
expand |
boolean |
Nem | false |
A beágyazott kérdőív-, kérdező-, válaszadó- és kampányobjektumok beemelése |
cursor |
string |
Nem | — | Lapozási kurzor egy korábbi oldalról |
limit |
integer |
Nem | 50 |
Oldalméret (legfeljebb 100) |
Visszatérési érték: { data: [...], next_cursor, has_more } – kurzoros lapozással. Minden kitöltés a status mellett egy származtatott, írásvédett completed logikai értéket is tartalmaz (pontosan akkor true, ha a status értéke "completed"); a status az egyetlen hiteles forrás, és a kitöltési felületen sehol nincs completed szűrő vagy bemenet.
update_survey
Szekció neve “update_survey”Egy kitöltés módosítható mezőinek frissítése. A hozzákötött entitások (kérdőív, válaszadó, kérdező, kampány) itt nem módosíthatók – az átkötésükhöz törölje és hozza létre újra a kitöltést.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
survey_id |
string |
Igen | — | A kitöltés UUID-ja |
status |
string |
Nem | — | Új állapot; a befejezést a "completed" beállítása fejezi ki (nincs külön completed bemenet) |
qml_state |
object |
Nem | — | Haladó: a kitöltés menetállapotának lecserélése |
current_block_id |
string |
Nem | — | Haladó: a menetmutató áthelyezése |
current_item_id |
string |
Nem | — | Haladó: a menetmutató áthelyezése |
Visszatérési érték: a frissített kitöltésobjektum (ugyanolyan alakú, mint a list_surveys bejegyzései, a completed a status értékéből származtatva).
create_survey
Szekció neve “create_survey”Új kitöltés létrehozása egy válaszadó számára.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A használandó kérdőív |
respondent_id |
string |
Igen | — | A válaszadó UUID-ja |
interviewer_user_id |
string |
Nem | — | Telefonos vagy személyes interjúkhoz. Önkitöltésnél hagyja el |
campaign_id |
string |
Nem | — | Hozzárendelés egy kampányhoz |
Visszatérési érték: { id, questionnaire_id, interviewer_user_id, respondent_id, campaign_id, mode }
A mode származtatott érték, nem állítható be: field_interview, ha kérdező van hozzákötve, ai_assisted, ha a válaszadó bármely válasza előtt a saját MI-asszisztensében adta meg a beleegyezését, egyébként direct. Ezen a felületen minden kitöltésobjektum tartalmazza. Lásd: Kitöltési mód.
Egy válaszadónak kampányonként legfeljebb egy élő kitöltése lehet. Ha a válaszadónak már van ilyen, a hívást a rendszer ütközésként (REST 409) utasítja el, megnevezve a meglévő kitöltés azonosítóját: folytassa azt, vagy előbb törölje.
bulk_create_surveys
Szekció neve “bulk_create_surveys”Kitöltések létrehozása egy kampányhoz rendelt válaszadói kör összes válaszadójának. Kihagyja azokat a válaszadókat, akiknek már van kitöltésük.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
campaign_id |
string |
Igen | — | A kampány UUID-ja |
Visszatérési érték:
{ "status": "success", "campaign_id": "...", "created_count": 45, "skipped_count": 5, "surveys": [{"id": "...", "respondent_id": "..."}]}Feltétel: a kampányhoz kérdőívet és válaszadói kört is hozzá kell rendelni.
get_survey_current_item
Szekció neve “get_survey_current_item”Egy kitöltés aktuális kérdésének lekérése. Az első híváskor inicializálja a kitöltés állapotát.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
survey_id |
string |
Igen | — | A kitöltés UUID-ja |
Visszatérési érték (kérdés): az aktuális elem a válaszlehetőségeivel és a vezérlőtípusával együtt – egyetlen hívás válasza mindent tartalmaz, ami a megválaszolásához kell.
{ "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}Csúszka vezérlőnél az options egyetlen tartományleírót tartalmaz:
{"control_type": "slider", "options": [{"type": "range", "min": 18, "max": 99, "step": 1}]}Az editbox, a range és a textarea vezérlő üres options listát ad vissza; a határaikat vagy a szövegbeállításaikat az elem input mezőjéből olvassa ki. Vezérlőtípusok: radio, dropdown, checkbox, slider, switch, editbox, range, textarea.
Visszatérési érték (befejezve): { survey_id, status: "completed", message: "..." }
submit_survey_response
Szekció neve “submit_survey_response”Válasz beküldése az aktuális kérdésre, és továbblépés a következő elemre.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
survey_id |
string |
Igen | — | A kitöltés UUID-ja |
item_id |
string |
Igen | — | A megválaszolt elem azonosítója |
outcome |
any |
Igen | — | A válasz értéke (a típusa a vezérlőtől függ; egy Range válasz [low, high] pár) |
Visszatérési érték:
{ "survey_id": "...", "status": "in_progress", "output": { }, "next": { }}A status értéke "in_progress" vagy "completed". A next a következő lépést tartalmazza (ugyanolyan alakban, mint a get_survey_current_item), így nincs szükség külön lekérésre – a kitöltés befejeztével értéke null. A záró megjegyzéselemeket a rendszer minden beküldés után automatikusan feldolgozza.
finish_survey
Szekció neve “finish_survey”Egy kitöltés megjelölése befejezettként, kifejezett hívással. Olyan kivételes esetekre szolgál, amikor az automatikus befejezés nem lép működésbe.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
survey_id |
string |
Igen | — | A kitöltés UUID-ja |
Visszatérési érték: { status: "success" | "already_complete", survey_id, message }.
mass_fill_surveys
Szekció neve “mass_fill_surveys”Aszinkron háttérfeladat sorba állítása, amely egy kampány összes függőben lévő kitöltését szintetikus tesztválaszokkal tölti fel. Ne használja valódi válaszadói adatokat tartalmazó kampányokon.
Az eszköz azonnal visszaad egy task_id azonosítót; a generálási ciklus háttérfeladatként fut a Portor saját workerén. Kérdezze le a get_task_status eszközzel, amíg a feladat végállapotba nem ér: completed (minden kitöltés elkészült), partial (egyes kitöltések elkészültek, mások sikertelenek – például hibás válaszadói adatok vagy egy átmeneti QML-hiba miatt) vagy failed (egyetlen kitöltés sem készült el – vagy a futás előtti validálás hibája miatt, például hiányzó kampány esetén, vagy mert a futás minden kitöltése sikertelen volt; a last_error megmagyarázza, miért). A három állapot kölcsönösen kizárja egymást: sikerek és hibák bármilyen keveréke partial eredményt ad, soha nem failed eredményt.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
campaign_id |
string |
Igen | — | A kampány UUID-ja |
distribution |
string |
Nem | "realistic" |
Stratégia: "realistic", "random" vagy "llm"; minden más értéket elutasít |
max_surveys |
integer |
Nem | — | Legfeljebb ennyi kitöltést tölt fel válaszokkal. null = az összes függőben lévő |
profiles |
string[] |
Nem | ["random"] |
Perszónaprofilok, körforgásos kiosztással |
concurrency |
integer |
Nem | 1 |
A belső ciklus feladatonkénti szálkészletének mérete |
| Megoszlás | Hogyan választja ki a válaszokat | Mire használja |
|---|---|---|
realistic |
A válaszadó demográfiai adatai és perszónaprofilja szerint súlyozva: a feleletválasztós kérdések profilfüggő súlyokat, a csúszkák Gauss-eloszlást, a szöveges bemenetek profilspecifikus kifejezéseket használnak | Nagy volumenű adatfolyam-tesztelés (gyors) |
random |
Egyenletes, demográfiai befolyás nélkül | Terheléses tesztelés (a leggyorsabb) |
llm |
Kérdésenként egy Claude Haiku-hívás, amely megkapja a perszónát, a válaszadó demográfiai adatait és a kitöltés minden korábbi válaszát, így a kitöltés önmagával konzisztens marad. Kérdésenként körülbelül egy másodperc | Hihető nyitott válaszok; MI-hitelesítő adatok szükségesek a profiljában |
Profilok: young_single, married_family, retired, high_income, random.
Visszatérési érték (szinkron módon, a sorba állítás validálása után):
{ "task_id": "f5b6c7d8-...", "status": "pending", "campaign_id": "...", "distribution": "realistic", "profiles": ["young_single", "retired"]}Kérdezze le a get_task_status(task_id) hívással, amíg a state értéke completed, partial vagy failed nem lesz. A status_text élő előrehaladást mutat (például "47 of 200 surveys processed"), végállapotban pedig a kitöltés összegzését (például "47 of 200 surveys filled (3 failed)"); hiba esetén a last_error megtisztított okot tartalmaz. Egy partial eredmény utáni újrapróbálkozáshoz hívja meg újra a mass_fill_surveys eszközt ugyanarra a kampányra – az eszköz csak a még be nem fejezett kitöltéseket dolgozza fel, így a már kitöltötteket kihagyja.
Megoszlási módok
Szekció neve “Megoszlási módok”| Mód | Motor | Sebesség | Leírás |
|---|---|---|---|
realistic |
Súlyozott véletlen | Gyors | Profilfüggő demográfiai súlyozás (alapértelmezés) |
random |
Egyenletes véletlen | Gyors | Tiszta véletlen, demográfiai befolyás nélkül |
llm |
Claude Haiku API | ~1 mp/kérdés | MI által generált, a perszónával konzisztens válaszok. Feltétele, hogy az Ön (vagy a szervezete) következtetési szolgáltatója az Anthropic API vagy az AWS Bedrock legyen, tárolt hitelesítő adattal |
Perszónaprofilok
Szekció neve “Perszónaprofilok”A rendszer körforgásos kiosztással rendeli őket a válaszadókhoz. Elérhető profilok:
| Profil | Életkor | Jövedelem | Viselkedés |
|---|---|---|---|
young_single |
25–35 | $65k | Progresszív, a technológiában jártas, a középső lehetőségeket részesíti előnyben |
married_family |
30–50 | $80k | Gyakorlatias, értékorientált |
retired |
65+ | $55k | Konzervatív, a lista elején álló/hagyományos lehetőségeket részesíti előnyben |
high_income |
45 | $150k+ | Minőségközpontú, a prémium lehetőségeket részesíti előnyben |
random |
40 | $70k | Nincs különösebb torzítása |
Az elemtípusok kezelése
Szekció neve “Az elemtípusok kezelése”A válaszok numerikus kódok (a feleletválasztós vezérlő labels mezője egész kódokat rendel a megjelenített szövegekhez; a beküldött érték a kód) – szabad szöveg csak a textarea vezérlőnél. A teljes specifikációt A kérdőív megjelenítési formátuma oldal ismerteti.
| Elemtípus | Válaszformátum | Példa |
|---|---|---|
Comment |
null (automatikusan átugorva) |
Tájékoztató szöveg |
Question |
Egyetlen szám: válaszkód / numerikus érték / kapcsoló 1-0 (Checkbox: egész számként megadott bitmaszk; Textarea: karakterlánc) |
2, 42, true |
QuestionGroup |
Számok listája, alkérdésenként egy – mind a csoport egyetlen közös vezérlőjéből | [1, 3, 2] |
MatrixQuestion |
Számok beágyazott listája, sorok × oszlopok – egy közös vezérlő | [[1, 2], [3, 1]] |
bulk_delete_surveys
Szekció neve “bulk_delete_surveys”Több kitöltés törlése szűrési feltételek alapján. Kétlépéses munkafolyamatot használ: először hívja meg dry_run=true értékkel, hogy előnézetben lássa, mit töröl majd az eszköz, aztán hívja meg újra dry_run=false értékkel a végrehajtáshoz.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
campaign_id |
string |
Igen | — | Ennek a kampánynak a kitöltéseit törli |
status |
string |
Nem | — | Csak az ilyen állapotú kitöltéseket célozza: "pending", "in_progress" vagy "completed" |
dry_run |
boolean |
Nem | true |
Előnézeti mód – törlés nélkül visszaadja a darabszámot és egy mintát |
Próbafuttatás visszatérési értéke:
{ "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."}Végrehajtás visszatérési értéke: { dry_run: false, deleted: 25 }
Hibakezelés
Szekció neve “Hibakezelés”Gyakori hibák
Szekció neve “Gyakori hibák”| Helyzet | Válasz |
|---|---|
| A kitöltés nem található | {"error": "Survey {id} not found"} |
| A kampány nem található | {"error": "Campaign {id} not found"} |
| A kérdőív nem található | {"error": "Questionnaire {id} not found"} |
| A kitöltés nincs inicializálva | {"error": "Survey not initialized. Call get_survey_current_item first."} |
| Nincs hozzárendelt válaszadói kör | {"error": "Campaign has no respondent pool assigned"} |
| Nincs befejezetlen kitöltés | {"status": "no_surveys", "message": "No incomplete surveys found in campaign"} |
A kitöltés állapotgépe
Szekció neve “A kitöltés állapotgépe”[Not Started] → get_survey_current_item → [In Progress][In Progress] → submit_survey_response → [In Progress | Completed][In Progress] → finish_survey → [Completed]- Inicializálás: a
get_survey_current_itemelső hívása betölti a QML-t, és létrehozza a kitöltés állapotát - Automatikus befejezés: a kitöltés automatikusan befejeződik, amikor az utolsó elemre is válasz érkezik
- A megjegyzések átugrása: a megjegyzéselemeket a rendszer észrevétlenül feldolgozza (legfeljebb 50 egymást követőt) – a hívók soha nem kapják meg őket
- Tartósság: minden válasz azonnal az adatbázisba kerül