Zum Inhalt springen
Wissensdatenbank

Umfrage-Tools – MCP-Tool-Referenz

Umfrage-Tools steuern den Ablauf der Durchführung: Umfragesitzungen anlegen, durch Fragebogenabläufe navigieren, Antworten übermitteln und synthetische Testdaten erzeugen. Comment-Elemente werden automatisch übersprungen – Aufrufer erhalten sie nie.

Umfragen auflisten, optional gefiltert nach Fragebogen, Kampagne, befragter Person, Interviewer oder Status.

Parameter Typ Erforderlich Standard Beschreibung
questionnaire_id string Nein — Nach Fragebogen-ID filtern
campaign_id string Nein — Nach Kampagnen-ID filtern
respondent_id string Nein — Nach Befragten-ID filtern
interviewer_user_id string Nein — Nach zugewiesenem Interviewer (Benutzer) filtern
status string Nein — Filter: "pending", "in_progress" oder "completed"
expand boolean Nein false Verschachtelte Objekte für Fragebogen/Interviewer/befragte Person/Kampagne befüllen
cursor string Nein — Paginierungs-Cursor einer vorherigen Seite
limit integer Nein 50 Seitengröße (max. 100)

Rückgabe: { data: [...], next_cursor, has_more } – Cursor-paginiert. Jede Umfrage enthält status sowie einen abgeleiteten, schreibgeschützten Boolean completed (true genau dann, wenn status gleich "completed" ist); status ist die einzige maßgebliche Quelle, und in der gesamten Umfrage-Schnittstelle gibt es weder einen Filter noch eine Eingabe completed.


Die veränderlichen Felder einer Umfrage ändern. Die gebundenen Entitäten (Fragebogen, befragte Person, Interviewer, Kampagne) sind hier unveränderlich – um sie neu zu binden, löschen Sie die Umfrage und legen sie neu an.

Parameter Typ Erforderlich Standard Beschreibung
survey_id string Ja — UUID der Umfrage
status string Nein — Neuer Status; mit "completed" drücken Sie den Abschluss aus (eine separate Eingabe completed gibt es nicht)
qml_state object Nein — Fortgeschritten: den Ablaufzustand der Umfrage ersetzen
current_block_id string Nein — Fortgeschritten: den Ablaufzeiger neu setzen
current_item_id string Nein — Fortgeschritten: den Ablaufzeiger neu setzen

Rückgabe: das geänderte Umfrageobjekt (gleiche Form wie die Einträge von list_surveys, completed aus status abgeleitet).


Eine neue Umfrage für eine befragte Person anlegen.

Parameter Typ Erforderlich Standard Beschreibung
questionnaire_id string Ja — Zu verwendender Fragebogen
respondent_id string Ja — UUID der befragten Person
interviewer_user_id string Nein — Für telefonische oder persönliche Interviews. Bei Selbstausfüllung weglassen
campaign_id string Nein — Einer Kampagne zuordnen

Rückgabe: { id, questionnaire_id, interviewer_user_id, respondent_id, campaign_id, mode }

mode wird abgeleitet, nie gesetzt: field_interview, wenn ein Interviewer gebunden ist, ai_assisted, sobald die befragte Person in ihrem KI-Assistenten eingewilligt hat, bevor sie eine Antwort gab, andernfalls direct. Jedes Umfrageobjekt dieser Schnittstelle enthält es. Siehe Umfragemodus.

Eine befragte Person hat pro Kampagne höchstens eine laufende Umfrage. Hat sie bereits eine, wird der Aufruf als Konflikt abgelehnt (REST 409), mit der ID dieser Umfrage: Setzen Sie sie fort oder löschen Sie sie zuerst.


Umfragen für alle Befragten im zugewiesenen Pool einer Kampagne anlegen. Befragte, die bereits Umfragen haben, werden übersprungen.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne

Rückgabe:

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

Voraussetzung: Der Kampagne müssen sowohl ein Fragebogen als auch ein Befragtenpool zugewiesen sein.


Die aktuelle Frage einer Umfrage abrufen. Beim ersten Aufruf wird der Umfragezustand initialisiert.

Parameter Typ Erforderlich Standard Beschreibung
survey_id string Ja — UUID der Umfrage

Rückgabe (Frage): das aktuelle Element mit eingebetteten Antwortoptionen und dem Steuerelementtyp – ein einziger Roundtrip liefert alles, was zum Antworten nötig ist.

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

Bei einem Slider-Steuerelement enthält options einen einzigen Bereichsdeskriptor:

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

Die Steuerelemente editbox, range und textarea liefern eine leere Liste options; lesen Sie ihre Grenzen oder Texteinstellungen aus dem input des Elements. Steuerelementtypen: radio, dropdown, checkbox, slider, switch, editbox, range, textarea.

Rückgabe (abgeschlossen): { survey_id, status: "completed", message: "..." }


Eine Antwort auf die aktuelle Frage übermitteln und zum nächsten Element weitergehen.

Parameter Typ Erforderlich Standard Beschreibung
survey_id string Ja — UUID der Umfrage
item_id string Ja — ID des beantworteten Elements
outcome any Ja — Antwortwert (der Typ hängt vom Steuerelement ab; eine Range-Antwort ist ein Paar [low, high])

Rückgabe:

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

status ist "in_progress" oder "completed". next bettet den folgenden Schritt ein (gleiche Form wie bei get_survey_current_item), sodass Sie ihn nicht separat abrufen müssen – sobald die Umfrage abgeschlossen ist, ist es null. Nachfolgende Comment-Elemente werden nach jeder Übermittlung automatisch verarbeitet.


Eine Umfrage ausdrücklich als abgeschlossen markieren. Für Sonderfälle, in denen der automatische Abschluss nicht greift.

Parameter Typ Erforderlich Standard Beschreibung
survey_id string Ja — UUID der Umfrage

Rückgabe: { status: "success" | "already_complete", survey_id, message }.


Einen asynchronen Hintergrund-Task einreihen, der alle ausstehenden Umfragen einer Kampagne mit synthetischen Testantworten füllt. Nicht für Kampagnen mit echten Befragtendaten verwenden.

Das Tool liefert sofort eine task_id; die Generierungsschleife läuft als Hintergrundjob auf Portors eigenem Worker. Fragen Sie get_task_status ab, bis der Task einen Endzustand erreicht: completed (jede Umfrage gefüllt), partial (einige Umfragen gefüllt, andere fehlgeschlagen – z. B. wegen fehlerhafter Befragtendaten oder eines vorübergehenden QML-Fehlers) oder failed (keine Umfrage gefüllt – entweder ein Validierungsfehler vor dem Lauf, etwa eine fehlende Kampagne, oder jede Umfrage des Laufs ist fehlgeschlagen; last_error erklärt den Grund). Die drei Zustände schließen einander aus: Jede Mischung aus Erfolgen und Fehlschlägen endet bei partial, nie bei failed.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne
distribution string Nein "realistic" Strategie: "realistic", "random" oder "llm"; jeder andere Wert wird abgelehnt
max_surveys integer Nein — Zahl der zu füllenden Umfragen begrenzen. null = alle ausstehenden
profiles string[] Nein ["random"] Persona-Profile, reihum zugewiesen
concurrency integer Nein 1 Größe des Thread-Pools je Task für die innere Schleife
Verteilung Wie Antworten gewählt werden Geeignet für
realistic Gewichtet nach Demografie und Persona-Profil der befragten Person: Auswahlfragen mit profilabhängigen Gewichten, Slider mit einer Gauß-Verteilung, Texteingaben mit profilspezifischen Formulierungen Pipeline-Tests mit hohem Volumen (schnell)
random Gleichverteilt, ohne demografischen Einfluss Belastungstests (am schnellsten)
llm Ein Claude-Haiku-Aufruf pro Frage, mit der Persona, der Demografie der befragten Person und jeder früheren Antwort in der Umfrage, sodass eine Umfrage in sich stimmig bleibt. Etwa eine Sekunde pro Frage Plausible offene Antworten; erfordert KI-Zugangsdaten in Ihrem Profil

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

Rückgabe (synchron, nach der Validierung beim Einreihen):

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

Fragen Sie get_task_status(task_id) ab, bis state den Wert completed, partial oder failed hat. status_text zeigt den laufenden Fortschritt (z. B. "47 of 200 surveys processed") und in einem Endzustand eine Zusammenfassung des Füllens (z. B. "47 of 200 surveys filled (3 failed)"); last_error enthält bei einem Fehlschlag einen bereinigten Grund. Um es nach einem partial-Ergebnis erneut zu versuchen, rufen Sie mass_fill_surveys noch einmal für dieselbe Kampagne auf – das Füllen verarbeitet nur Umfragen, die noch nicht abgeschlossen sind, bereits gefüllte werden also übersprungen.

Modus Engine Geschwindigkeit Beschreibung
realistic Gewichteter Zufall Schnell Profilbezogene demografische Gewichtung (Standard)
random Gleichverteilter Zufall Schnell Reiner Zufall, ohne demografischen Einfluss
llm Claude-Haiku-API ~1 s/Frage KI-generierte, zur Persona passende Antworten. Erfordert, dass Ihr Reasoning-Anbieter (oder der Ihrer Organisation) Anthropic API oder AWS Bedrock ist und dessen Zugangsdaten gespeichert sind

Reihum auf Befragte verteilt. Verfügbare Profile:

Profil Alter Einkommen Verhalten
young_single 25–35 $65k Progressiv, technikaffin, bevorzugt mittlere Optionen
married_family 30–50 $80k Pragmatisch, preisbewusst
retired 65+ $55k Konservativ, bevorzugt frühe/traditionelle Optionen
high_income 45 $150k+ Qualitätsorientiert, bevorzugt Premium-Optionen
random 40 $70k Keine besondere Tendenz

Antworten sind numerische Codes (die labels eines Auswahl-Steuerelements ordnen ganzzahligen Codes Anzeigetexte zu; übermittelt wird der Code) – Freitext nur beim Steuerelement textarea. Den vollständigen Vertrag finden Sie unter Darstellungsformat von Umfragen.

Elementart Format der Antwort Beispiel
Comment null (automatisch übersprungen) Informationstext
Question Eine einzelne Zahl: Antwortcode / numerischer Wert / Switch 1-0 (Checkbox: Bitmasken-Integer; Textarea: String) 2, 42, true
QuestionGroup Liste von Zahlen, eine je Unterfrage – alle aus dem einen gemeinsamen Steuerelement der Gruppe [1, 3, 2]
MatrixQuestion Verschachtelte Liste von Zahlen, Zeilen × Spalten – ein gemeinsames Steuerelement [[1, 2], [3, 1]]

Mehrere Umfragen nach Filterkriterien löschen. Verwendet einen zweistufigen Ablauf: Rufen Sie zuerst mit dry_run=true auf, um zu sehen, was gelöscht würde, und dann erneut mit dry_run=false, um es auszuführen.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — Umfragen in dieser Kampagne löschen
status string Nein — Nur Umfragen mit diesem Status betreffen: "pending", "in_progress" oder "completed"
dry_run boolean Nein true Vorschaumodus – liefert Anzahl und Stichprobe, ohne zu löschen

Rückgabe des Probelaufs:

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

Rückgabe bei Ausführung: { dry_run: false, deleted: 25 }


Situation Antwort
Umfrage nicht gefunden {"error": "Survey {id} not found"}
Kampagne nicht gefunden {"error": "Campaign {id} not found"}
Fragebogen nicht gefunden {"error": "Questionnaire {id} not found"}
Umfrage nicht initialisiert {"error": "Survey not initialized. Call get_survey_current_item first."}
Kein Pool zugewiesen {"error": "Campaign has no respondent pool assigned"}
Keine unvollständigen Umfragen {"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]
  • Initialisierung: Der erste Aufruf von get_survey_current_item lädt das QML und legt den Umfragezustand an
  • Automatischer Abschluss: Umfragen werden automatisch abgeschlossen, sobald das letzte Element beantwortet ist
  • Überspringen von Comments: Comment-Elemente werden unbemerkt verarbeitet (bis zu 50 aufeinanderfolgende) – Aufrufer erhalten sie nie
  • Persistenz: Jede Antwort wird sofort in der Datenbank gespeichert