Harness del Agente de Onboarding — LeadFlow × CULTIVA IA

1 Flujo del Agente · Granularidad de Herramientas

🔍

verify_registration

micro

→

🔐

check_email_confirmed

micro

→

🏗️

create_default_workspace

medium

→

📧

send_welcome_email

medium

→

📅

schedule_demo (cond.)

medium

→

📋

log_crm_activity

medium

→

✅

finalize_onboarding

macro

Micro — operación de alto riesgo, atómica, nunca combinable

Medium — edit/read/send de uso frecuente

Macro — resumen final cuando el round-trip es el coste dominante

2 Definición de Herramientas · Contratos de Input / Output

MICRO verify_registration Valida que el usuario existe y tiene datos mínimos

Input Schema

{
  "user_id": string,       // UUID LeadFlow
  "require_fields": ["email","name"]
}

Output (success)

{
  "status": "success",
  "summary": "User valid",
  "next_actions": [
    "check_email_confirmed"],
  "artifacts": {"plan": "growth"}
}

Output (error)

{
  "status": "error",
  "code": "USER_NOT_FOUND",
  "hint": "user_id puede ser incorrecto",
  "retry": false,
  "stop": true
}

MEDIUM create_default_workspace Crea pipeline con etapas estándar para el plan dado

Input Schema

{
  "user_id": string,
  "plan": "starter|growth|pro",
  "idempotency_key": string
}

Output (success)

{
  "status": "success",
  "summary": "Workspace created",
  "next_actions": ["send_welcome_email"],
  "artifacts": {
    "workspace_id": "ws_abc123"}
}

Output (error)

{
  "status": "error",
  "code": "DUPLICATE_WORKSPACE",
  "hint": "ya existe; usar idempotency_key",
  "retry": false,
  "stop": false
}

MEDIUM send_welcome_email Envía email de bienvenida personalizado vía Resend

Input Schema

{
  "user_id": string,
  "workspace_id": string,
  "template": "welcome_v2",
  "locale": "es|en"
}

Output (success)

{
  "status": "success",
  "summary": "Email enviado",
  "next_actions": [
    "schedule_demo",
    "log_crm_activity"],
  "artifacts": {"email_id": "re_x9z"}
}

Output (error)

{
  "status": "warning",
  "code": "EMAIL_RATE_LIMIT",
  "hint": "esperar 30s y reintentar",
  "retry": true,
  "retry_after_s": 30
}

MEDIUM schedule_demo Reserva demo 1:1 en Calendly (solo Growth + Pro)

Input Schema

{
  "user_id": string,
  "plan": string,
  "preferred_locale": string
  // Solo ejecutar si plan != "starter"
}

Output (success)

{
  "status": "success",
  "summary": "Demo link sent",
  "next_actions": ["log_crm_activity"],
  "artifacts": {
    "calendly_url": "cly.io/demo/abc"}
}

Output (skip)

{
  "status": "success",
  "summary": "Plan starter, skip demo",
  "next_actions": ["log_crm_activity"],
  "artifacts": {}
}

3 Formato de Observaciones · Contrato Estándar

Respuesta SUCCESS — create_default_workspace

{
  "status": "success",
  "summary": "Workspace 'LeadFlow Growth' creado con
  6 etapas de pipeline (Prospecto → Ganado/Perdido)",
  "next_actions": [
    "send_welcome_email con workspace_id=ws_abc123"
  ],
  "artifacts": {
    "workspace_id": "ws_abc123",
    "stages": ["Prospecto", "Contactado",
                 "Propuesta", "Negociación",
                 "Ganado", "Perdido"]
  },
  "tokens_used": 312,
  "phase": "workspace_setup"
}

Respuesta ERROR — verify_registration

{
  "status": "error",
  "summary": "Usuario usr_999 no encontrado en LeadFlow DB",
  "code": "USER_NOT_FOUND",
  "hint": "El user_id puede ser incorrecto o el registro
  aún no se propagó. Verificar con get_registration_event.",
  "retry": false,
  "stop": true,
  "stop_reason": "No se puede continuar sin usuario válido.
  Escalar a soporte con trace_id para investigación.",
  "next_actions": ["STOP — notificar soporte"],
  "artifacts": {},
  "phase": "registration_check"
}

Respuesta WARNING — send_welcome_email

{
  "status": "warning",
  "summary": "Rate limit Resend API (429). Email no enviado.",
  "code": "EMAIL_RATE_LIMIT",
  "hint": "Esperar retry_after_s segundos. Si falla 3 veces
  → encolar en job asíncrono y continuar flujo.",
  "retry": true,
  "retry_count": 1,
  "retry_after_s": 30,
  "next_actions": ["send_welcome_email (retry 2/3)"],
  "artifacts": {},
  "phase": "email_send"
}

Respuesta SUCCESS — finalize_onboarding (macro)

{
  "status": "success",
  "summary": "Onboarding completado para usr_421 (Growth)",
  "next_actions": [],
  "artifacts": {
    "workspace_id": "ws_abc123",
    "email_sent": true,
    "demo_scheduled": true,
    "crm_logged": true,
    "duration_ms": 2140,
    "total_tokens": 1872
  },
  "phase": "done"
}

4 Contratos de Recuperación de Errores

Código Error	Herramienta	Pista de Causa	Instrucción de Reintento	Condición de Stop
USER_NOT_FOUND	verify_registration	user_id incorrecto o propagación pendiente	NO RETRY	STOP · Escalar a soporte
EMAIL_NOT_CONFIRMED	check_email_confirmed	Usuario no hizo clic en el link de verificación	RETRY x1 tras 60s · reenviar confirmación	Tras 2 intentos → STOP · marcar pendiente
DUPLICATE_WORKSPACE	create_default_workspace	Workspace ya existe (idempotencia violada)	SKIP + CONTINUE · usar workspace existente	No detener — recuperable
EMAIL_RATE_LIMIT	send_welcome_email	Resend API 429 — límite de envíos	RETRY x3 con backoff 30/60/120s	Tras 3 intentos → ENQUEUE async · continuar
CALENDLY_UNAVAILABLE	schedule_demo	API Calendly caída o sin slots disponibles	SKIP + CONTINUE · enviar link manual por email	No bloquea el onboarding
CRM_WRITE_TIMEOUT	log_crm_activity	Timeout >5s en escritura CRM interno	RETRY x2 · luego ENQUEUE async	No bloquea — el log es asíncrono
CONTEXT_BUDGET_EXCEEDED	Agente (sistema)	Contexto superó 8K tokens antes del fin de tarea	COMPACT al límite de fase actual	Si ocurre 2 veces → STOP · revisar skills cargadas

5 Presupuesto de Contexto · 8.000 Tokens Máximo

Distribución por capa · Agente Onboarding LeadFlow Referencia: 128K ventana · reserva activa: 8K

System prompt (invariante)

sistema

≤ 600 tok

Skills on-demand (cargadas)

skills

≤ 800 tok

Historial de conversación

historial

≤ 1.200 tok

Outputs de herramientas (acumulado)

tool outputs

≤ 1.600 tok

Reserva de planning (ReAct)

reserva

≤ 400 tok

Total máximo por tarea de onboarding

Compactar al inicio de cada fase (no por umbral de tokens arbitrario)

4.600 tok típico · 8.000 tok límite

6 Patrón de Arquitectura · Híbrido ReAct + Function-calling

🧠 ReAct Planning Layer
El LLM razona el próximo paso: evalúa el estado actual, decide qué herramienta ejecutar y por qué. No ejecuta directamente.

↓

⚙️ Function-calling Execution Layer
7 herramientas tipadas con schemas estrictos. El LLM no infiere parámetros — los recibe como artifacts de la capa anterior. Inputs siempre validados antes de la llamada.

↓

📤 Observation Layer
Cada tool response sigue el contrato: status / summary / next_actions / artifacts. El agente consume next_actions para planificar el siguiente ciclo ReAct.

↓

🛡️ Error Recovery Layer
Cada error lleva hint + retry flag + stop condition. El agente nunca queda en bucle infinito ni en estado inconsistente. La tarea puede terminar en DONE, SKIP o STOP.

7 Anti-Patrones Corregidos · Antes vs Después

🔴 Herramientas combinadas (causa más frecuente de fallo)

Antes (prototipo)

create_workspace_and_send_email(user_id, plan) // Un solo call que hace 2 cosas // Si falla el email, el workspace queda en limbo

Después (harness)

create_default_workspace(user_id, plan) // → artifacts.workspace_id send_welcome_email(user_id, workspace_id) // Atómico; cada paso verificable

🔴 Errores opacos sin pistas de recuperación

Antes (prototipo)

{ "error": "500 Internal Server Error" } // El agente no sabe qué hacer → bucle de 4+ reintentos // → tarea abandonada

Después (harness)

{ "status": "error", "code": "DUPLICATE_WORKSPACE", "hint": "workspace ya existe, usar existente", "retry": false, "stop": false } // El agente recupera en 1 paso, no pierde contexto

🔴 System prompt sobrecargado (4.000 tokens)

Antes (prototipo)

SYSTEM: [documentación API completa, 4.000 tokens] // Ocupa 50% del presupuesto en tareas simples // El agente pierde contexto de planificación

Después (harness)

SYSTEM: [reglas esenciales, 600 tokens] // Docs API → skill on-demand cargada solo cuando // el agente encuentra un error de parámetros

🔴 Sin condición de stop explícita

Antes (prototipo)

// El agente sigue reintentando sin límite // USER_NOT_FOUND x12 intentos → timeout // Tarea cuesta 8x tokens innecesarios

Después (harness)

USER_NOT_FOUND → retry: false, stop: true // El agente para en el 1er intento // Registra stop_reason, notifica soporte // Tokens por tarea fallida: 400 vs 3.200 antes

8 Proyección de Métricas · Antes vs Después del Harness

Tasa Finalización

61%

→

≥90%

objetivo: +29 pp

Reintentos / Tarea

avg 4.2

→

≤1.3

contratos de error explícitos

pass@1 (1er intento)

~48%

→

~78%

herramientas atómicas

Costo / Tarea Exitosa

~0,08€

→

~0,03€

presupuesto contexto -60%

Harness del Agente de Onboarding · LeadFlow