Tovább a tartalomhoz
Tudástár

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.

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.


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


Ú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.


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.


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: "..." }


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.


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 }.


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.

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

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

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]]

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 }


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"}
[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_item első 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