Generación agéntica de respuestas
Este documento describe la simulación de campañas, una función en la que agentes de IA generan respuestas sintéticas a partir de perfiles de persona y que permite probar campañas hipotéticas antes de lanzarlas de verdad.
Descripción general
Sección titulada «Descripción general»La simulación de campañas permite probar escenarios hipotéticos con datos sintéticos. Los agentes de IA responden las encuestas como encuestados virtuales y generan respuestas realistas según perfiles demográficos y rasgos de comportamiento.
Casos de uso
Sección titulada «Casos de uso»- Validar el flujo y la lógica del cuestionario antes del lanzamiento real
- Probar los procesos de análisis de datos con datos sintéticos realistas
- Formar a los entrevistadores con sesiones de encuesta simuladas
- Estimar los recursos necesarios para ejecutar la campaña
- Generar datos de demostración para presentaciones ante las partes interesadas
Modos de generación de respuestas
Sección titulada «Modos de generación de respuestas»Respuestas generadas por LLM (recomendado)
Sección titulada «Respuestas generadas por LLM (recomendado)»El modo distribution="llm" utiliza Claude Haiku para generar respuestas coherentes con el contexto a partir de perfiles de persona. Cada pregunta la responde un LLM que recibe el perfil de persona completo y todos los pares de pregunta y respuesta anteriores, de modo que las respuestas son coherentes a lo largo de toda la encuesta.
Principales ventajas frente a la generación basada en reglas:
- Coherencia contextual: un encuestado que responde «desempleado» no describirá más adelante su lugar de trabajo
- Lenguaje natural: las respuestas de texto abierto reflejan el estilo de comunicación del perfil
- Elecciones matizadas: la selección de opciones tiene en cuenta todo el contexto de la pregunta, no solo un azar ponderado
Requisitos: su proveedor de Razonamiento (Configuración del perfil → Modelos de IA), o el de su organización, debe ser Anthropic API o AWS Bedrock, con sus credenciales guardadas. El llenado se factura a esa cuenta, nunca a una clave de la plataforma. Si no hay ningún proveedor configurado o faltan sus credenciales, el modo falla de inmediato, antes de procesar ninguna encuesta: no se recurre en silencio a ninguna alternativa.
Ejemplo:
User: result = mass_fill_surveys(campaign_id="abc", distribution="llm", profiles=["young_single", "retired"]) # result = {"task_id": "...", "status": "pending"} # poll get_task_status(task_id=result["task_id"]) until terminal
Result (after the task completes): Young Professional answering "How often do you shop online?" → "Several times a week" (tech-savvy, time-conscious)
Retired Senior answering the same question → "A few times a month" (traditional, deliberate shopper)Respuestas basadas en reglas
Sección titulada «Respuestas basadas en reglas»El modo predeterminado, distribution="realistic", aplica una selección aleatoria ponderada según los perfiles demográficos. Es más rápido, pero tiene menos en cuenta el contexto: resulta adecuado para probar procesos de datos con grandes volúmenes cuando la calidad de las respuestas importa menos.
| Distribución | Método | Velocidad | Calidad |
|---|---|---|---|
llm |
Claude Haiku por pregunta | ~1 s/pregunta | Alta: contextual y coherente |
realistic |
Azar ponderado | Instantánea | Media: influida por la demografía |
random |
Azar puro | Instantánea | Baja: sin influencia demográfica |
Simulación de campañas (tres fases)
Sección titulada «Simulación de campañas (tres fases)»Simule el ciclo de vida completo de una campaña con varios encuestados.
Fase 1: Preparación
Sección titulada «Fase 1: Preparación»- Crea el proyecto, el cuestionario y la campaña
- Genera encuestados sintéticos con datos demográficos realistas
- Crea la estrategia de muestreo y el grupo de encuestados
- Crea en bloque las encuestas de todos los encuestados
Fase 2: Ejecución
Sección titulada «Fase 2: Ejecución»- Completa las encuestas con respuestas generadas a partir de los perfiles de persona
- Simula patrones de respuesta realistas según la demografía
- Gestiona las ramificaciones y los saltos del cuestionario
Fase 3: Análisis
Sección titulada «Fase 3: Análisis»- Extrae las respuestas al conjunto de datos Bronce
- Aplica la ponderación por posestratificación: raking (calibración por rastrillado)
- Crea los conjuntos de datos Plata y Oro
- Exporta en varios formatos (CSV, XLSX, SPSS, Parquet, R, JSON)
Perfiles de persona
Sección titulada «Perfiles de persona»Los perfiles de persona definen las características que guían la generación de respuestas sintéticas. Cada uno reúne atributos demográficos y rasgos de comportamiento que influyen en su forma de responder.
Los atributos de sus propios encuestados se suman al perfil
Sección titulada «Los atributos de sus propios encuestados se suman al perfil»Un perfil de persona es un arquetipo; el encuestado al que representa es un registro concreto de su proyecto. Cuando se genera una respuesta sintética para un encuestado real, los atributos de ese encuestado se añaden al perfil: su edad, su género y su ubicación, y todos los atributos personalizados que haya registrado para él.
En los atributos personalizados suelen estar las características por las que un estudio segmenta realmente: tamaño de la empresa, sector, región, nivel de afiliación o lo que haya traído su importación. Ahora esos atributos llegan al encuestado simulado, de modo que un perfil que responde en nombre de una microempresa del sector bancario responde como tal, y no como un arquetipo genérico que casualmente comparte la franja de edad.
Dos consecuencias que conviene conocer:
- Un atributo real prevalece sobre uno personalizado del mismo nombre. Si registra un atributo personalizado llamado
location, se impone el campo de ubicación propio del encuestado: al encuestado simulado nunca se le dan dos respuestas distintas a la misma pregunta sobre sí mismo. - Los atributos por los que pondera son los que ve el perfil. Los factores de calibración ya pueden construirse a partir de atributos personalizados, así que esto cierra una brecha: antes era posible ponderar una muestra según una característica que nunca se había comunicado a los encuestados simulados.
Perfiles integrados
Sección titulada «Perfiles integrados»| Perfil | Datos demográficos | Características de las respuestas |
|---|---|---|
| Young Professional | 25-35 años, soltero, con empleo, ingresos de 50 000-80 000 $ | Afín a la tecnología, valora su tiempo, respuestas breves |
| Family Oriented | 30-50 años, casado, con hijos, zona residencial periférica | Decisiones centradas en la familia, respuestas detalladas |
| Retired Senior | 65 años o más, jubilado, ingresos fijos | Valores tradicionales, respuestas minuciosas |
| High Earner | 35-55 años, ingresos altos (>100 000 $) | Prioriza la calidad, preferencias de gama alta |
| Random | Datos demográficos variados | Patrones de respuesta impredecibles |
Estructura de un perfil
Sección titulada «Estructura de un perfil»Cada perfil de persona se define con:
name: Young Professionaldescription: Young adult professional, tech-savvy and time-conscious
demographics: age_range: 25-35 gender: any marital_status: single employment: full-time professional income: $50,000 - $80,000 education: bachelor's degree location: urban/suburban
behavioral_traits: - tech-savvy - time-conscious - values convenience - early adopter
response_style: verbosity: brief decision_speed: quick detail_level: moderatePerfiles personalizados
Sección titulada «Perfiles personalizados»Los usuarios pueden crear perfiles a medida para necesidades de investigación concretas:
User: "Create a persona for budget-conscious students"
AI: Creating custom persona: Budget Student
Demographics: - Age: 18-24 - Employment: Part-time or student - Income: < $25,000 - Education: Currently enrolled - Location: University town
Behavioral Traits: - Price-sensitive - Social media active - Peer-influenced decisions - Values free trials/samples
Response Style: - Casual language - Quick decisions - Strong opinions on value
Save this persona for future simulations?Generación de respuestas
Sección titulada «Generación de respuestas»Cómo funcionan las respuestas del LLM
Sección titulada «Cómo funcionan las respuestas del LLM»Para cada pregunta de la encuesta, el LLM recibe un único prompt que contiene:
- Prompt del sistema: el texto del perfil de persona, con sus datos demográficos y rasgos de comportamiento
- Datos demográficos del encuestado: los datos reales del registro del encuestado (edad, género, nivel de estudios, etc.)
- Historial de preguntas y respuestas: todos los pares anteriores de pregunta y respuesta de esta sesión de encuesta
- Pregunta actual: el texto de la pregunta, las opciones disponibles y el formato de respuesta JSON esperado
El LLM devuelve una respuesta JSON estructurada que se convierte al formato que espera el motor de encuestas (un valor único, una lista o un diccionario, según el tipo de pregunta).
Historial de la conversación
Sección titulada «Historial de la conversación»Cada encuesta mantiene un historial acumulado de pares de pregunta y respuesta. Este historial se incluye en cada prompt posterior, lo que permite al LLM:
- Mantener la coherencia: quien dijo «desempleado» no describirá más tarde un lugar de trabajo
- Apoyarse en el contexto: las valoraciones de satisfacción concuerdan con las experiencias positivas o negativas mencionadas antes
- Evitar contradicciones: las respuestas demográficas se mantienen coherentes entre sí
Formato de respuesta según el tipo de pregunta
Sección titulada «Formato de respuesta según el tipo de pregunta»Las respuestas son los códigos enteros del mapa labels de la pregunta (texto libre solo en las preguntas abiertas de tipo Textarea); consulte Formato de presentación de encuestas:
| Tipo de pregunta | Formato esperado | Ejemplo |
|---|---|---|
| Opción única (radio/desplegable) | Un código de respuesta | 2 |
| Opción múltiple (casillas) | Lista de los códigos seleccionados (el analizador la reduce a una máscara de bits) | [1, 4] |
| Control deslizante (numérico) | Número dentro del rango | 7 |
| Rango (intervalo) | Par [low, high] dentro del rango, con el mínimo no superior al máximo |
[3, 8] |
| Interruptor (booleano) | true / false |
true |
| Texto abierto (textarea) | Cadena | "Great service overall" |
| Grupo de preguntas | Lista de códigos, uno por subpregunta (un único control compartido) | [1, 3, 2] |
| Pregunta de matriz | Lista anidada de códigos, filas × columnas | [[1, 2], [3, 1]] |
Flujo de trabajo del investigador
Sección titulada «Flujo de trabajo del investigador»Combinación de perfiles → llenado masivo → análisis
Sección titulada «Combinación de perfiles → llenado masivo → análisis»El flujo recomendado para generar datos sintéticos con respuestas del LLM:
- Diseñe su combinación de perfiles: elija cuáles incluir y en qué proporción
- Llame a
mass_fill_surveyscondistribution="llm"y los perfiles elegidos - Cree el conjunto de datos Bronce: extraiga las respuestas sin procesar
- Aplique raking: pondere las respuestas para que coincidan con la demografía objetivo
- Exporte y analice: CSV, XLSX, SPSS, Parquet, R o JSON
Ejemplo: llamada a una herramienta MCP
Sección titulada «Ejemplo: llamada a una herramienta MCP»# Enqueue the background fill task (returns immediately with a task_id)result = mass_fill_surveys( campaign_id="campaign-uuid", distribution="llm", profiles=["young_single", "married_family", "retired", "high_income"], max_surveys=50,)# result = {"task_id": "...", "status": "pending", ...}
# Poll until terminalwhile True: status = get_task_status(task_id=result["task_id"]) if status["state"] in ("completed", "partial", "failed"): break sleep(5)La herramienta responde de inmediato; el bucle de generación se ejecuta como tarea en segundo plano en el propio worker de Portor. La consulta periódica muestra status_text (por ejemplo, "23 of 50 surveys processed"). Hay tres estados finales distintos: completed (todas las encuestas completadas), partial (una mezcla: el resumen del llenado aparece en status_text, y volver a invocar mass_fill_surveys solo reintenta las encuestas sin completar) y failed (ninguna encuesta completada, con un last_error que explica el motivo).
Configuración mediante chat
Sección titulada «Configuración mediante chat»User: "Run a simulation of the NPS campaign with 50 respondents, mostly young professionals and families, using LLM responses"
AI: Configuring simulation:
Campaign: NPS Customer Satisfaction Distribution: LLM (Claude Haiku) Respondents: 50 synthetic profiles
Persona Distribution: - Young Professional: 40% (20 respondents) - Family Oriented: 40% (20 respondents) - Random: 20% (10 respondents)
Each survey will maintain conversation history for consistent responses.
Output: - Bronze dataset (raw responses) - Silver dataset (weighted) - XLSX export
Start simulation?Resultados de la simulación
Sección titulada «Resultados de la simulación»Cuando termina la simulación, los usuarios reciben:
1. Resumen de la campaña
Sección titulada «1. Resumen de la campaña»Simulation Complete: "Q1 Satisfaction Test Run"
Surveys:- Total: 100- Completed: 98- Terminated (screening): 2
Response Statistics:- Average completion time: 6m 42s- Questions answered: 1,470- Skip rate: 8.3%
NPS Results:- Promoters (9-10): 34%- Passives (7-8): 41%- Detractors (0-6): 25%- NPS Score: +92. Informe de calidad de los datos
Sección titulada «2. Informe de calidad de los datos»Demographic Distribution vs. Targets:
┌─────────────┬──────────┬──────────┬─────────┐│ Factor │ Target │ Actual │ RMSE │├─────────────┼──────────┼──────────┼─────────┤│ Male │ 48% │ 47% │ 0.01 ││ Female │ 50% │ 51% │ 0.01 ││ Age 18-24 │ 15% │ 14% │ 0.01 ││ Age 25-34 │ 25% │ 26% │ 0.01 ││ Age 35-44 │ 25% │ 24% │ 0.01 │└─────────────┴──────────┴──────────┴─────────┘
Overall Quality: ✅ Excellent (RMSE: 0.012)Weighting Efficiency: 94% (Design Effect: 1.06)3. Conjuntos de datos exportables
Sección titulada «3. Conjuntos de datos exportables»| Conjunto de datos | Descripción | Formato |
|---|---|---|
| Bronce | Respuestas sin procesar, tal como se recogieron | Parquet |
| Plata | Respuestas ponderadas (con raking aplicado) | Parquet |
| Oro | Depurado y listo para exportar | CSV, XLSX, SPSS |
Arquitectura
Sección titulada «Arquitectura»Enfoque de SDK directo
Sección titulada «Enfoque de SDK directo»La generación por LLM de mass_fill_surveys utiliza una única llamada sin estado al LLM por pregunta: el motor askalot_ai.respondent_sim, que Portor invoca directamente en lugar de pasar por el ejecutor de agentes de varios turnos. Es una decisión deliberada:
- Portor ya tiene el estado de la encuesta en el propio proceso mediante
FlowProcessor, así que no hace falta que un agente llame a herramientas MCP que acabarían de nuevo en el propio Portor - Cada pregunta es una llamada directa («con este perfil y las respuestas dadas hasta ahora, responda a esta pregunta»)
- Sin llamadas MCP circulares, con una gestión de errores más sencilla y menor latencia
Esto es distinto del agente Encuestado (el flujo complete-survey), que recorre una encuesta completa turno a turno mediante herramientas MCP y se utiliza dentro de la simulación de campañas: la vía de llenado masivo sacrifica esa profundidad agéntica a cambio de rendimiento.
| Aspecto | Configuración |
|---|---|
| Modelo | Claude Haiku 4.5 (claude-haiku-4-5-20251001) |
| Tokens máximos | 256 por respuesta |
| Temperatura | 0,8 (variación natural) |
| Contexto | Perfil de persona + datos demográficos del encuestado + historial de preguntas y respuestas |
Procesamiento por lotes
Sección titulada «Procesamiento por lotes»Dentro de mass_fill_surveys, las encuestas se completan de forma secuencial. Cada encuesta acumula su propio historial de preguntas y respuestas para mantener la coherencia interna, sin depender de las demás encuestas.
Perfiles de persona
Sección titulada «Perfiles de persona»Los archivos de perfil son documentos Markdown con front matter YAML, montados en los contenedores de Portor desde el directorio compartido de prompts de askalot_ai. El modo LLM y el modo basado en reglas utilizan los mismos perfiles.
Proveedor
Sección titulada «Proveedor»El modo LLM utiliza solo Anthropic: Claude Haiku ofrece el mejor equilibrio entre velocidad, coste y calidad para generar respuestas de encuesta. El servicio de inferencia local de la plataforma se utiliza únicamente para los embeddings de documentos, no para generar respuestas.
Buenas prácticas
Sección titulada «Buenas prácticas»Cuándo utilizar la simulación
Sección titulada «Cuándo utilizar la simulación»- Antes de lanzar campañas costosas
- Al probar nuevos diseños de cuestionario
- Para formar a los analistas en el proceso de datos
- Para validar estrategias de muestreo
- Para generar datos de demostración para presentaciones ante las partes interesadas
Limitaciones de la simulación
Sección titulada «Limitaciones de la simulación»- No son opiniones reales: los datos sintéticos reflejan perfiles arquetípicos, no actitudes reales
- Coherencia frente a variedad: los perfiles sintéticos pueden ser más coherentes que las personas reales
- Casos límite: las combinaciones de respuestas poco habituales pueden estar infrarrepresentadas
- Preguntas abiertas: el texto generado por IA puede carecer de una diversidad auténtica
- Dependencia de la API: el modo LLM requiere un proveedor de razonamiento Anthropic API o AWS Bedrock con credenciales válidas, además de acceso a Internet
- Sin señal de tiempo de respuesta: las respuestas generadas se registran como producidas por una máquina y quedan excluidas a propósito de la detección de encuestados demasiado rápidos (speeders), de modo que una campaña simulada no ofrece una distribución de tiempos significativa: esa comprobación solo resulta informativa cuando responden encuestados reales
Gestión de errores
Sección titulada «Gestión de errores»El modo LLM sigue el principio de la plataforma de «sin alternativas silenciosas»:
- Sin proveedor o sin credenciales: falla de inmediato, antes de procesar ninguna encuesta, e indica qué hay que configurar
- Errores de la API: los fallos de encuestas concretas se registran y se notifican en el resultado
- JSON no válido del LLM: la encuesta falla y se notifica en el resultado. La excepción es una pregunta de texto libre: en ese caso, la propia respuesta del LLM se registra como respuesta
- Sin degradación silenciosa: el modo nunca cambia por su cuenta a la generación basada en reglas
Recomendaciones
Sección titulada «Recomendaciones»- Utilice el modo LLM cuando importe la calidad: cuando el realismo de las respuestas sea relevante (presentaciones, pruebas de análisis)
- Utilice el modo basado en reglas cuando importe la velocidad: cuando necesite mucho volumen rápidamente (pruebas de carga del proceso de datos)
- Combine perfiles: incluya el perfil «random» para aportar variedad
- Compare con pilotos: valide los patrones de la simulación con pequeñas muestras reales
- Documente los datos sintéticos: etiquete claramente los conjuntos de datos como simulados
Documentación relacionada
Sección titulada «Documentación relacionada»- Gestión de campañas asistida por IA: configuración y gestión de campañas
- Análisis de datos: el proceso Bronce → Plata → Oro
- Gestión de campañas: conceptos básicos de las campañas