Runbook — cultiva-agentes-api

Campo	Valor
Servicio	cultiva-agentes-api
Owner	equipo-plataforma (Álvaro Gimeno)
Entorno	production
Infraestructura	Railway (API) + Cloudflare (CDN/WAF)
Última verificación	2026-06-12
SLA	99.5% uptime · P95 latencia < 2 s
Slack alerts	#alerts-prod

---

Descripción general

API REST que orquesta los agentes de IA de CULTIVA: generación de contenido para clientes, análisis de métricas de campañas y automatizaciones de marketing.
Impacto crítico si falla: todos los clientes del plan Agency pierden acceso a las automatizaciones en tiempo real.

Dependencias externas:

Servicio	Criticidad	URL de estado
Supabase (PostgreSQL)	Alta	https://status.supabase.com
Upstash Redis	Media	https://upstash-status.com
Anthropic API	Alta	https://status.anthropic.com
OpenAI API	Media	https://status.openai.com
Cloudflare	Alta	https://www.cloudflarestatus.com

---

Precondiciones

• Acceso a Railway dashboard con rol Admin
• Acceso a Supabase dashboard proyecto cultiva-prod
• Acceso a Slack canal #alerts-prod y #eng-oncall
• Variables de entorno disponibles en Railway → cultiva-agentes-api → Variables
• Railway CLI instalado: npm install -g @railway/cli

---

Procedimiento de arranque

1. Verificar que las dependencias externas están operativas (ver tabla arriba).
2. Confirmar que las variables de entorno críticas están presentes en Railway.
3. Desplegar o reiniciar el servicio desde Railway.

# Autenticarse con Railway CLI
railway login

# Seleccionar entorno
railway environment production

# Reinicar el servicio (restart sin redeploy)
railway service restart cultiva-agentes-api

# Verificar logs de arranque (primeros 60 s)
railway logs --service cultiva-agentes-api --tail 100

1. Confirmar que el proceso está ACTIVE en el dashboard de Railway.
2. Ejecutar health check manual (ver sección siguiente).

---

Procedimiento de parada controlada

1. Notificar en #alerts-prod: "Iniciando parada controlada de cultiva-agentes-api — ETA 5 min".
2. Activar Cloudflare Maintenance Page para la ruta /api/* si la parada supera 2 minutos.
3. Drenar el tráfico: esperar que las métricas de Railway bajen a 0 req/s activos.
4. Detener el servicio desde Railway dashboard o CLI.

# Detener servicio (Railway mantiene el config, solo para el proceso)
railway service stop cultiva-agentes-api

# Confirmar que no quedan workers activos
railway logs --service cultiva-agentes-api --tail 20
# Esperado: "Server shutdown complete" o sin nuevos logs

1. Confirmar parada en #alerts-prod.

---

Health Checks

Check rápido (< 30 segundos)

# Health endpoint público
curl -sf https://api.cultiva-ia.com/health | jq .

# Esperado:
# { "status": "ok", "db": "connected", "redis": "connected", "uptime_s": 3721 }

# Check de autenticación (requiere API key de test)
curl -sf -H "Authorization: Bearer $CULTIVA_TEST_KEY" \
  https://api.cultiva-ia.com/v1/agents/ping | jq .

# Esperado: { "pong": true, "latency_ms": 45 }

Checks de dependencias

# Supabase — conectividad directa
psql "$SUPABASE_DB_URL" -c "SELECT NOW();"

# Redis — Upstash
redis-cli -u "$UPSTASH_REDIS_URL" PING
# Esperado: PONG

# Anthropic API — modelo disponible
curl -sf https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":1,"messages":[{"role":"user","content":"ping"}]}' | jq .type

Umbrales de alerta

Métrica	Warning	Critical
Error rate	> 1%	> 5%
Latencia P95	> 1.5 s	> 3 s
Cola Redis	> 500 jobs	> 2000 jobs
Conexiones DB	> 80	> 95

---

Checklist de despliegue

[ ] 1. CI verde en GitHub Actions (rama main)
[ ] 2. Migraciones de DB revisadas y testeadas en staging
[ ] 3. Variables de entorno nuevas añadidas en Railway Production
[ ] 4. Notificación en #eng-oncall: "Deploy cultiva-agentes-api vX.Y.Z iniciando"
[ ] 5. Railway deploy desde dashboard o:
        railway up --service cultiva-agentes-api --detach
[ ] 6. Smoke checks durante 5 minutos post-deploy
[ ] 7. Observar error rate y latencia en Railway Metrics 10-15 min
[ ] 8. Notificación en #eng-oncall: "Deploy completado OK / ROLLBACK iniciado"

---

Rollback

Activar si: error rate > 5% en los primeros 10 min post-deploy, o degradación crítica de latencia.

1. Identificar el último despliegue estable en Railway → Deployments.
2. Hacer clic en Rollback sobre ese deployment (o usar CLI).

# Listar deployments recientes
railway deployments list --service cultiva-agentes-api

# Rollback al deployment anterior (sustituir <DEPLOY_ID>)
railway deployment rollback <DEPLOY_ID>

# Verificar que el rollback arrancó correctamente
railway logs --service cultiva-agentes-api --tail 50

1. Ejecutar health checks completos (ver sección Health Checks).
2. Comunicar en #alerts-prod: "Rollback a vX.Y.Z completado — servicio estable".
3. Revertir variables de entorno si el deploy incluyó cambios de config.

---

Respuesta a incidentes

Clasificación de severidad

Nivel	Criterio	Tiempo de respuesta
SEV-1	Servicio caído totalmente, todos los clientes impactados	< 15 min
SEV-2	Degradación severa (>20% errores), clientes Agency impactados	< 30 min
SEV-3	Degradación parcial, impacto limitado	< 2 h
SEV-4	Comportamiento anómalo sin impacto visible	Próxima jornada

Playbook de diagnóstico

# 1. Ver logs de error de los últimos 5 minutos
railway logs --service cultiva-agentes-api --tail 200 | grep -i "error\|fatal\|exception"

# 2. Verificar uso de memoria y CPU en Railway Metrics

# 3. Comprobar jobs atascados en Redis
redis-cli -u "$UPSTASH_REDIS_URL" LLEN cultiva:jobs:failed

# 4. Verificar conexiones activas a Supabase
psql "$SUPABASE_DB_URL" -c "SELECT count(*), state FROM pg_stat_activity GROUP BY state;"

# 5. Verificar rate limits de APIs externas
# Anthropic: cabecera x-ratelimit-remaining-requests en las respuestas
# OpenAI: cabecera x-ratelimit-remaining-requests

---

Escalación

Nivel	Responsable	Contacto
L1	On-call engineer	Slack @oncall-cultiva · PagerDuty
L2	Service owner	Álvaro Gimeno — @alvaro en Slack
L3	Liderazgo de Plataforma	Canal privado #crisis-room

Regla de escalación: si no hay resolución en 20 min para SEV-1 o 45 min para SEV-2, escalar automáticamente al siguiente nivel.

---

Post-incidente

Plantilla de postmortem

## Postmortem — cultiva-agentes-api — [FECHA]

**Resumen:** [1 párrafo]
**Severidad:** SEV-X
**Duración:** HH:MM — HH:MM (X minutos de impacto)
**Clientes afectados:** N clientes / planes afectados

### Timeline
- HH:MM — Alerta disparada en #alerts-prod
- HH:MM — On-call notificado
- HH:MM — Causa raíz identificada
- HH:MM — Mitigación aplicada
- HH:MM — Servicio restaurado

### Causa raíz
[Descripción técnica detallada]

### Acciones correctivas
| Acción | Owner | Fecha límite |
|---|---|---|
| [Acción 1] | @persona | YYYY-MM-DD |

### Actualizaciones a este runbook
[Qué secciones necesitan actualización]

---

Generado con generador-runbooks-operacionales · CULTIVA IA · 2026-06-12