Ir al contenido
Base de conocimiento

Herramientas de encuesta — Referencia de herramientas MCP

Las herramientas de encuesta gestionan el ciclo de ejecución de las encuestas: crear sesiones de encuesta, recorrer el flujo de los cuestionarios, enviar respuestas y generar datos de prueba sintéticos. Los ítems de tipo comentario se omiten automáticamente: quien llama nunca los recibe.

Lista las encuestas, opcionalmente filtradas por cuestionario, campaña, encuestado, entrevistador o estado.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string No — Filtra por ID de cuestionario
campaign_id string No — Filtra por ID de campaña
respondent_id string No — Filtra por ID de encuestado
interviewer_user_id string No — Filtra por entrevistador asignado (usuario)
status string No — Filtro: "pending", "in_progress" o "completed"
expand boolean No false Rellena los objetos anidados de cuestionario, entrevistador, encuestado y campaña
cursor string No — Cursor de paginación de una página anterior
limit integer No 50 Tamaño de página (máximo 100)

Devuelve: { data: [...], next_cursor, has_more }, con paginación por cursor. Cada encuesta incluye status y un booleano derivado de solo lectura, completed (true exactamente cuando status es "completed"); status es la única fuente de verdad, y ninguna herramienta de encuestas tiene un filtro ni un dato de entrada completed.


Actualiza los campos modificables de una encuesta. Las entidades vinculadas (cuestionario, encuestado, entrevistador, campaña) no se pueden modificar aquí: elimine la encuesta y vuelva a crearla para cambiar esos vínculos.

Parámetro Tipo Obligatorio Predeterminado Descripción
survey_id string Sí — UUID de la encuesta
status string No — Nuevo estado; establecer "completed" es la forma de expresar la finalización (no existe un dato de entrada completed aparte)
qml_state object No — Avanzado: sustituye el estado del flujo de la encuesta
current_block_id string No — Avanzado: cambia la posición del puntero del flujo
current_item_id string No — Avanzado: cambia la posición del puntero del flujo

Devuelve: el objeto de la encuesta actualizado (con la misma forma que las entradas de list_surveys, con completed derivado de status).


Crea una encuesta nueva para un encuestado.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — Cuestionario que se utilizará
respondent_id string Sí — UUID del encuestado
interviewer_user_id string No — Para entrevistas telefónicas o presenciales. Omítalo en las encuestas autoadministradas
campaign_id string No — Asocia la encuesta a una campaña

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

mode se deriva y nunca se establece: field_interview cuando hay un entrevistador vinculado, ai_assisted cuando el encuestado dio su consentimiento en su asistente de IA antes de dar cualquier respuesta y direct en los demás casos. Todos los objetos de encuesta que devuelven estas herramientas lo incluyen. Consulte Modo de la encuesta.

Un encuestado tiene como máximo una encuesta activa por campaña. Si el encuestado ya tiene una, la llamada se rechaza como conflicto (REST 409) indicando el ID de esa encuesta: continúela o elimínela primero.


Crea encuestas para todos los encuestados del grupo asignado a una campaña. Omite a los encuestados que ya tienen encuesta.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña

Devuelve:

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

Requisitos: la campaña debe tener asignados tanto un cuestionario como un grupo de encuestados.


Obtiene la pregunta actual de una encuesta. En la primera llamada inicializa el estado de la encuesta.

Parámetro Tipo Obligatorio Predeterminado Descripción
survey_id string Sí — UUID de la encuesta

Devuelve (pregunta): el ítem actual, con sus opciones de respuesta incluidas, y el tipo de control: una sola ida y vuelta contiene todo lo necesario para responder.

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

En un control deslizante (slider), options contiene un único descriptor de rango:

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

Los controles editbox, range y textarea devuelven una lista options vacía; lea sus límites o su configuración de texto en el input del ítem. Tipos de control: radio, dropdown, checkbox, slider, switch, editbox, range, textarea.

Devuelve (completada): { survey_id, status: "completed", message: "..." }


Envía una respuesta a la pregunta actual y avanza al ítem siguiente.

Parámetro Tipo Obligatorio Predeterminado Descripción
survey_id string Sí — UUID de la encuesta
item_id string Sí — ID del ítem que se responde
outcome any Sí — Valor de la respuesta (el tipo depende del control; una respuesta de tipo Range es un par [low, high])

Devuelve:

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

status es "in_progress" o "completed". next incluye el paso siguiente (con la misma forma que get_survey_current_item), así que no necesita una consulta aparte; es null cuando la encuesta se completa. Los ítems de comentario que siguen se procesan automáticamente después de cada envío.


Marca explícitamente una encuesta como completada. Úsela en los casos excepcionales en que la finalización automática no se produce.

Parámetro Tipo Obligatorio Predeterminado Descripción
survey_id string Sí — UUID de la encuesta

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


Pone en cola una tarea asíncrona en segundo plano que rellena todas las encuestas pendientes de una campaña con respuestas de prueba sintéticas. No la use en campañas con datos reales de encuestados.

La herramienta devuelve un task_id de inmediato; el bucle de generación se ejecuta como trabajo en segundo plano en el propio worker de Portor. Consulte get_task_status hasta que la tarea llegue a un estado final: completed (se rellenaron todas las encuestas), partial (se rellenaron algunas y otras fallaron, p. ej. por datos de encuestado incorrectos o por un error transitorio de QML) o failed (no se rellenó ninguna encuesta, ya sea por un error de validación previo a la ejecución, como una campaña inexistente, o porque fallaron todas las encuestas de la ejecución; last_error explica el motivo). Los tres estados son excluyentes: cualquier combinación de éxitos y fallos termina en partial, nunca en failed.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña
distribution string No "realistic" Estrategia: "realistic", "random" o "llm"; cualquier otro valor se rechaza
max_surveys integer No — Límite de encuestas que se rellenan. null = todas las pendientes
profiles string[] No ["random"] Perfiles de persona, asignados de forma rotativa
concurrency integer No 1 Tamaño del grupo de hilos de cada tarea para el bucle interno
Distribución Cómo se eligen las respuestas Para qué usarla
realistic Ponderadas según los datos demográficos y el perfil de persona del encuestado: las preguntas de elección usan pesos que dependen del perfil; los controles deslizantes, una gaussiana; y los campos de texto, frases propias de cada perfil Pruebas del proceso a gran volumen (rápida)
random Uniforme, sin influencia demográfica Pruebas de carga (la más rápida)
llm Una llamada a Claude Haiku por pregunta, con el perfil de persona, los datos demográficos del encuestado y todas las respuestas anteriores de la encuesta, de modo que cada encuesta es coherente consigo misma. Aproximadamente un segundo por pregunta Respuestas abiertas verosímiles; requiere credenciales de IA en su perfil

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

Devuelve (de forma síncrona, tras validar la puesta en cola):

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

Consulte get_task_status(task_id) hasta que state sea completed, partial o failed. status_text muestra el progreso en directo (p. ej. "47 of 200 surveys processed") y, en un estado final, un resumen del relleno (p. ej. "47 of 200 surveys filled (3 failed)"); last_error contiene un motivo saneado en caso de fallo. Para reintentar tras un resultado partial, vuelva a invocar mass_fill_surveys sobre la misma campaña: el relleno solo procesa las encuestas que aún no están completadas, de modo que las ya rellenadas se omiten.

Modo Motor Velocidad Descripción
realistic Aleatorio ponderado Rápida Ponderación demográfica según el perfil (predeterminado)
random Aleatorio uniforme Rápida Totalmente aleatorio, sin influencia demográfica
llm API de Claude Haiku ~1 s/pregunta Respuestas generadas por IA y coherentes con el perfil de persona. Requiere que su proveedor de razonamiento (o el de su organización) sea la API de Anthropic o AWS Bedrock, con sus credenciales guardadas

Se asignan de forma rotativa a los encuestados. Perfiles disponibles:

Perfil Edad Ingresos Comportamiento
young_single 25–35 $65k Progresista, con soltura tecnológica, prefiere las opciones intermedias
married_family 30–50 $80k Práctico, orientado a la relación calidad-precio
retired 65+ $55k Conservador, prefiere las primeras opciones o las tradicionales
high_income 45 $150k+ Centrado en la calidad, prefiere las opciones prémium
random 40 $70k Sin ningún sesgo particular

Las respuestas son códigos numéricos (las labels de un control de elección asignan códigos enteros a textos visibles; lo que se envía es el código); solo el control textarea admite texto libre. Consulte Formato de presentación de encuestas para el contrato completo.

Tipo de ítem Formato de la respuesta Ejemplo
Comment null (se omite automáticamente) Texto informativo
Question Un solo número: código de respuesta / valor numérico / interruptor 1-0 (Checkbox: entero de máscara de bits; Textarea: cadena) 2, 42, true
QuestionGroup Lista de números, uno por subpregunta, todos del único control compartido del grupo [1, 3, 2]
MatrixQuestion Lista anidada de números, filas × columnas, con un control compartido [[1, 2], [3, 1]]

Elimina varias encuestas según criterios de filtro. Sigue un flujo en dos pasos: llame primero con dry_run=true para previsualizar lo que se eliminará y después vuelva a llamar con dry_run=false para ejecutarlo.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — Elimina las encuestas de esta campaña
status string No — Solo afecta a las encuestas con este estado: "pending", "in_progress" o "completed"
dry_run boolean No true Modo de vista previa: devuelve el recuento y una muestra sin eliminar nada

La simulación (dry run) devuelve:

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

La ejecución devuelve: { dry_run: false, deleted: 25 }


Situación Respuesta
Encuesta no encontrada {"error": "Survey {id} not found"}
Campaña no encontrada {"error": "Campaign {id} not found"}
Cuestionario no encontrado {"error": "Questionnaire {id} not found"}
Encuesta no inicializada {"error": "Survey not initialized. Call get_survey_current_item first."}
Sin grupo asignado {"error": "Campaign has no respondent pool assigned"}
No hay encuestas incompletas {"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]
  • Inicialización: la primera llamada a get_survey_current_item carga el QML y crea el estado de la encuesta
  • Finalización automática: las encuestas se completan automáticamente cuando se responde al último ítem
  • Omisión de comentarios: los ítems de comentario se procesan de forma transparente (hasta 50 consecutivos); quien llama nunca los recibe
  • Persistencia: cada respuesta se guarda de inmediato en la base de datos