← Volver al listado de tecnologías ← Índice de Paperclip

Presupuestos y gobernanza: control sin babysitting

Por: Artiko
paperclippresupuestogobernanzacostosboard

El problema del gasto descontrolado en IA

Antes de hablar de cómo Paperclip resuelve el control de costos, conviene entender por qué es un problema real y no teórico.

Imagina que tienes un agente configurado para revisar código en cada PR. El mes que tu equipo tuvo un sprint intenso con 80 PRs en lugar de los habituales 20, el costo de ese agente se multiplicó por cuatro. Sin un sistema de control, ese costo llegó a tu tarjeta de crédito al final del mes como una sorpresa desagradable.

O peor: un agente tiene un bug en su configuración que lo hace entrar en un loop, generando cientos de llamadas a la API antes de que alguien lo note. En sistemas sin límites, eso puede costar cientos o miles de dólares en horas.

Paperclip resuelve esto con un modelo de presupuesto jerárquico y un sistema de gobernanza que hace al Board el árbitro final de todos los recursos.

El modelo de presupuesto jerárquico

El presupuesto en Paperclip fluye de arriba hacia abajo, igual que en una empresa real:

graph TD
    Company[Presupuesto de Empresa: $200/mes]
    CEO[CEO Felipe: $20/mes]
    CTO[CTO Ana: $40/mes]
    Support[Head of Support: $20/mes]
    Eng1[Rafa Senior: $50/mes]
    Eng2[María Jr: $30/mes]
    Bot[Soporte L1: $40/mes]
    
    Company --> CEO
    Company --> CTO
    Company --> Support
    CTO --> Eng1
    CTO --> Eng2
    Support --> Bot
    
    Total["Total asignado: $200"]
    Company --> Total

Reglas del modelo jerárquico:

  1. La suma de los presupuestos individuales no puede superar el presupuesto de empresa. Si intentas asignar $250 en agentes cuando el presupuesto de empresa es $200, el sistema muestra un warning.

  2. Un agente no puede gastar más que su presupuesto individual, aunque el presupuesto de empresa no esté agotado.

  3. El manager puede redistribuir presupuesto entre sus reports dentro del límite que tiene él mismo. El CTO puede mover $10 de Rafa a María si lo justifica.

  4. Solo el Board puede aumentar presupuestos (el de empresa o el de cualquier agente).

Configurar el presupuesto de un agente

Cada agente tiene su propio objeto de Budget. Configurarlo correctamente desde el principio evita sorpresas:

# Configuración completa de presupuesto para un agente
budget:
  agentId: agent_eng_rafa
  
  # Límites
  monthlyLimitUsd: 50.00
  dailyLimitUsd: 5.00           # Opcional: límite diario adicional
  perTaskLimitUsd: 10.00        # Opcional: límite por tarea individual
  
  # Alertas
  warningThreshold: 0.80        # Notificar al 80% (default)
  criticalThreshold: 0.90       # Notificar al 90% (default)
  
  # Comportamiento al agotar
  onExhausted: pause            # pause | notify_only | cascade_to_manager
  
  # Reinicio automático
  resetPeriod: monthly          # monthly | weekly | manual
  resetDay: 1                   # Día del mes para reinicio mensual
  
  # Tracking de costos
  trackByTask: true             # Atribuir cada gasto a una tarea específica
  trackByToolCall: true         # Registrar el costo de cada tool call
  trackByModel: true            # Desglosar costos por modelo usado

El campo onExhausted es especialmente importante:

Cálculo de costos en tiempo real

Paperclip calcula el costo de cada operación usando los precios oficiales de los proveedores. Los precios se actualizan automáticamente (o manualmente si prefieres control total):

// Tabla de precios internos de Paperclip (ejemplo, los precios reales varían)
{
  "claude-opus-4-5": {
    "inputTokensPer1M": 15.00,
    "outputTokensPer1M": 75.00
  },
  "claude-sonnet-4-5": {
    "inputTokensPer1M": 3.00,
    "outputTokensPer1M": 15.00
  },
  "claude-haiku-3-5": {
    "inputTokensPer1M": 0.25,
    "outputTokensPer1M": 1.25
  },
  "gpt-4o": {
    "inputTokensPer1M": 5.00,
    "outputTokensPer1M": 15.00
  }
}

Cada vez que un agente hace una llamada a un LLM, el adapter reporta los tokens usados, Paperclip calcula el costo, lo registra en el BudgetTransaction, y actualiza el spentThisMonthUsd del agente.

Para adapters de tipo process o http que no usan LLMs, el costo es 0 a menos que el adapter lo reporte explícitamente en su respuesta:

// El adapter HTTP puede reportar costo
{
  "status": "completed",
  "summary": "...",
  "costUsd": 0.05,    // Si tu sistema tiene costos propios
  "tokensUsed": 0
}

Dashboard de costos

El panel de costos de Paperclip te da visibilidad completa del gasto:

Company → Budget → Dashboard

El dashboard muestra:

Vista mensual por agente:

Agente                 Presupuesto  Gastado  Restante  % Usado
─────────────────────────────────────────────────────────────
Felipe García (CEO)    $20.00       $8.43    $11.57    42%
Ana Martínez (CTO)     $40.00       $31.22   $8.78     78% ⚠️
Carlos López (Support) $20.00       $5.11    $14.89    26%
Rafa Torres (Senior)   $50.00       $42.78   $7.22     86% 🔴
María García (Jr)      $30.00       $12.45   $17.55    42%
Bot24/7 (Soporte L1)   $40.00       $18.90   $21.10    47%
─────────────────────────────────────────────────────────────
Total empresa          $200.00      $118.89  $81.11    59%

Rafa y Ana están en zona de alerta. El Board recibe notificaciones en este caso.

Vista por tarea:

Tarea                                    Agente        Costo
───────────────────────────────────────────────────────────
Migrar tabla invoices                    Rafa Torres   $8.32
Code review PR #247                      Ana Martínez  $3.14
Resolver ticket cliente #789             Bot24/7       $0.82
Planificar sprint Q2                     Felipe CEO    $2.11
Escribir tests módulo auth               Rafa Torres   $4.67

Proyección fin de mes: El sistema proyecta el gasto de fin de mes basándose en la tasa de gasto actual:

Tasa actual de gasto: $118.89 / 15 días = $7.93/día
Proyección para el mes (30 días): $237.80
Presupuesto mensual: $200.00
Déficit proyectado: $37.80

Agentes en riesgo de agotarse antes de fin de mes:
  - Rafa Torres: se agotará en ~2 días
  - Ana Martínez: se agotará en ~3 días

Esta proyección alerta al Board con tiempo suficiente para ajustar presupuestos o reducir la carga de trabajo de los agentes en riesgo.

Qué pasa cuando se agota el presupuesto

El comportamiento cuando un agente agota su presupuesto está diseñado para minimizar el impacto operacional mientras se mantiene el control:

sequenceDiagram
    participant Agent as Rafa Torres
    participant Sys as Sistema
    participant Mgr as CTO Ana
    participant Board as Board (Tú)
    
    Agent->>Sys: Intenta tomar nueva tarea
    Sys->>Sys: Verifica presupuesto: $0 restante
    Sys->>Agent: Checkout rechazado: budget_exhausted
    Sys->>Mgr: Notificación: "Rafa Torres agotó su presupuesto"
    Sys->>Board: Notificación urgente + dashboard actualizado
    
    alt Board aumenta presupuesto
        Board->>Sys: Aumentar budget de Rafa: +$20
        Sys->>Agent: Budget restaurado, puede reanudar
    else Manager redistribuye
        Mgr->>Sys: Transferir $10 de María a Rafa
        Sys->>Agent: Budget restaurado: $10
    else Board espera al reinicio
        Board->>Sys: Mantener hasta fin de mes
        Sys->>Agent: Status: budget_exhausted hasta reinicio
    end

Las tareas que estaban in_progress cuando se agota el presupuesto tienen comportamiento especial:

Redistribución de presupuesto

El Board puede redistribuir presupuesto de varias formas:

Aumentar el presupuesto de un agente:

Board → Budget → [Agente] → Adjust Budget
Nueva cantidad: $60 (antes $50)
Justificación: "Sprint intensivo Q2, crítico completar migración"

Transferir presupuesto entre agentes:

Board → Budget → Transfer
De: María García Jr ($17.55 restante)
A: Rafa Torres Senior ($0 restante)
Cantidad: $10
Justificación: "Migración urgente, María tiene trabajo de menor prioridad"

Reinicio manual del presupuesto:

Board → Budget → [Agente] → Reset Budget
Confirmar: "¿Estás seguro de reiniciar el presupuesto de Rafa Torres?"

Todas estas acciones quedan registradas en el audit log con la justificación del Board. Esto es importante para accountability: si en el futuro te preguntas por qué el gasto del mes fue mayor de lo esperado, puedes ver exactamente qué ajustes de presupuesto se hicieron y por qué.

Approval gates del Board

El Board no solo gestiona presupuesto. Tiene poder de aprobación sobre acciones estratégicas del sistema. Los approval gates son los puntos donde el flujo normal se pausa y espera confirmación del Board.

Gate 1: Contratación de nuevos agentes

Cada vez que se crea un nuevo agente, el Board recibe una solicitud de aprobación antes de que el agente entre en producción. La solicitud incluye:

El Board puede aprobar, rechazar (con razón), o aprobar con modificaciones.

Gate 2: Cambios de estrategia del CEO

Si el CEO propone un cambio significativo de estrategia (cambiar la prioridad de una iniciativa, iniciar una nueva área de trabajo, cambiar la estructura del org chart), la propuesta va al Board antes de implementarse.

El CEO crea la propuesta como una tarea con tipo strategy_proposal:

Tipo: strategy_proposal
Título: "Pivotar focus del Q2: priorizar pipeline CI/CD sobre refactoring"
Descripción: [justificación detallada con datos]
Impacto: [qué cambia, qué deja de hacerse, costo estimado]

El Board recibe la propuesta, puede pedir clarificaciones (respondiendo en la tarea), y finalmente aprueba o rechaza.

Gate 3: Gastos grandes por tarea

Si la configuración tiene perTaskLimitUsd: 10.00 y el agente detecta que una tarea específica requerirá más de ese límite, crea una solicitud de aprobación antes de continuar:

Aprobación requerida:
Agente: Rafa Torres
Tarea: "Migración completa del módulo de facturación"
Estimación de costo: $18.40 (por encima del límite de $10 por tarea)
Razón: La migración requiere 3 ejecuciones de script + verificación completa
Aprobar / Rechazar / Aprobar con límite diferente

Gate 4: Acciones de alto riesgo

Ciertos adapters pueden marcar acciones específicas como “high_risk” que requieren aprobación del Board:

# En la configuración del adapter
adapterConfig:
  highRiskActions:
    - pattern: "kubectl apply"
      requireBoardApproval: true
    - pattern: "pg_dump"
      requireBoardApproval: false   # Backups son ok sin approval
    - pattern: "git push.*main"
      requireBoardApproval: true

Los poderes completos del Board

El Board tiene un conjunto completo de poderes que garantizan el control humano sobre el sistema en todo momento:

graph LR
    Board[Board] --> P1[Pausar / Reanudar agentes]
    Board --> P2[Override de tareas]
    Board --> P3[Gestión de presupuestos]
    Board --> P4[Aprobación de contrataciones]
    Board --> P5[Aprobación de estrategia]
    Board --> P6[Audit completo]
    Board --> P7[Rollback de configuración]
    Board --> P8[Broadcast a todos los agentes]

Pausar / Reanudar agentes: Puedes pausar cualquier agente en cualquier momento. Un agente pausado:

# Via API
curl -X POST http://localhost:3100/api/agents/agent_eng_rafa/pause \
  -d '{"reason": "Audit de seguridad en curso"}'

# Reanudar
curl -X POST http://localhost:3100/api/agents/agent_eng_rafa/resume

Override de tareas: El Board puede modificar cualquier tarea: cambiar el assignee, cambiar la prioridad, inyectar contexto adicional, o cancelarla. Cada override queda en el audit log con la razón especificada.

Broadcast a todos los agentes: El Board puede enviar un mensaje a todos los agentes simultáneamente. Esto se usa para comunicar cambios importantes de estrategia, nuevas restricciones, o contexto urgente:

Board → Broadcast
Mensaje: "URGENTE: Se detectó una vulnerabilidad de seguridad en la dependencia 
lodash. Todos los agentes deben pausar cualquier deploy hasta que la actualización 
sea aplicada y verificada. El CTO coordinará el proceso."
Alcance: Todos los agentes (o solo un rol específico)

Los agentes reciben el broadcast en su próxima ejecución como parte del contexto del sistema.

Governance con rollback: Si un cambio de configuración produce resultados inesperados, el Board puede revertir a una versión anterior:

# Ver historial de configuraciones
npx paperclipai config:history --company devco --agent agent_ceo_felipe

# Hacer rollback a una versión específica
npx paperclipai config:rollback \
  --agent agent_ceo_felipe \
  --version "2026-04-01T09:00:00Z"

El sistema mantiene un historial de todas las configuraciones de agentes, presupuestos, y org chart. Puedes revertir a cualquier punto en el tiempo.

Estrategias de gobernanza por madurez del equipo

La gobernanza óptima depende de cuánto confías en tus agentes y cuánto tiempo llevan operando. Paperclip soporta diferentes perfiles de gobernanza:

Perfil “Piloto automático” (confianza alta, sistema maduro):

boardConfig:
  supervisionLevel: minimal
  requireApproval:
    hiring: true              # Siempre requiere aprobación
    strategyChanges: true     # Siempre requiere aprobación
    largeExpenses: false      # Confías en los límites de presupuesto
    deployToProduction: false # El CI/CD pipeline tiene sus propias salvaguardas
  notifications:
    dailySummary: true
    criticalOnly: true
    budgetWarnings: true

Perfil “Supervisión activa” (confianza media, sistema en rodaje):

boardConfig:
  supervisionLevel: active
  requireApproval:
    hiring: true
    strategyChanges: true
    largeExpenses: true       # Revisar gastos > $10 por tarea
    deployToProduction: true  # Aprobar cada deploy
  notifications:
    allAgentActivities: false
    taskCompletions: true
    escalations: true
    dailySummary: true

Perfil “Control total” (confianza baja, sistema nuevo o sensible):

boardConfig:
  supervisionLevel: full
  requireApproval:
    hiring: true
    strategyChanges: true
    largeExpenses: true
    deployToProduction: true
    newTaskCreation: true     # Incluso crear tareas requiere aprobación
    agentCommunications: true # Revisar @mentions antes de que el agente las vea
  notifications:
    allActivities: true
    realTime: true

El perfil de control total puede volverse agotador rápidamente. La recomendación es empezar en “Supervisión activa” y ir relajando los controles conforme los agentes demuestran comportamiento confiable.

Métricas de eficiencia y ROI

El sistema de presupuesto de Paperclip no solo controla gastos: también te permite calcular el retorno de inversión de tus agentes.

Si sabes que un ticket de soporte de primera línea tiene un valor de $15 (tiempo del equipo humano que ahorra), y el Bot24/7 resuelve 200 tickets por mes gastando $40, el ROI es:

Valor generado: 200 tickets × $15 = $3,000
Costo: $40/mes
ROI: ($3,000 - $40) / $40 = 74x

Paperclip no calcula este ROI automáticamente (porque el valor depende de tu negocio), pero te da todos los datos para hacerlo:

Exporta estos datos mensualmente y combínalos con el valor de negocio de cada tipo de trabajo para tener una imagen clara del ROI de tu inversión en agentes IA.

Con la gobernanza configurada correctamente, tienes una empresa de agentes que opera de forma autónoma dentro de límites bien definidos, con trazabilidad completa y control humano en los puntos que importan. El siguiente capítulo cubre cómo llevar este sistema a producción: PostgreSQL externo, Docker, acceso remoto, y todos los detalles de un deployment serio.

← Volver al listado de tecnologías ← Índice de Paperclip