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

Sistema de tickets: gestión de trabajo y trazabilidad

5 de abril de 2026 Por: Artiko

paperclipticketstareasaudit logtrazabilidad

Por qué el sistema de tickets es el corazón de Paperclip

Muchas personas, cuando descubren Paperclip, se enfocan primero en los agentes y los heartbeats. Eso es comprensible: la idea de agentes que trabajan solos es la parte más llamativa. Pero la parte que hace la diferencia entre un sistema de automatización y una empresa real es el sistema de tickets.

El sistema de tickets es lo que garantiza que nada se pierde, nada es ambiguo, y todo es auditable. Sin un sistema de tickets sólido, tienes agentes activos que hacen cosas que no puedes rastrear, costos que no puedes atribuir, y responsabilidades que no puedes asignar.

Con el sistema de tickets de Paperclip, cada unidad de trabajo tiene un historial completo: quién la creó, quién la tomó, qué hizo exactamente, cuánto costó, y cuál fue el resultado. Eso transforma una orquestación de agentes en una empresa real.

La jerarquía de tareas

Paperclip organiza el trabajo en cuatro niveles:

graph TD
    I[Iniciativa] --> P1[Proyecto A]
    I --> P2[Proyecto B]
    P1 --> T1[Tarea 1]
    P1 --> T2[Tarea 2]
    T1 --> ST1[Subtarea 1.1]
    T1 --> ST2[Subtarea 1.2]
    T2 --> ST3[Subtarea 2.1]

Iniciativa: El nivel más alto. Corresponde a un objetivo de negocio grande que puede tardar semanas o meses. Ejemplo: “Refactoring del módulo de facturación”. Una iniciativa puede tener múltiples proyectos.

Proyecto: Un conjunto coherente de tareas que logra una parte de la iniciativa. Ejemplo: “Migrar el modelo de datos de facturación”. Un proyecto puede tener múltiples tareas.

Tarea: La unidad de trabajo principal. Es lo que se asigna a un agente, lo que tiene checkout atómico, y lo que aparece en el kanban board. Ejemplo: “Crear esquema de migración para la tabla invoices”.

Subtarea: Desglose de una tarea en pasos más pequeños. Los propios agentes pueden crear subtareas cuando trabajan en una tarea compleja. Ejemplo: “Escribir script de migración”, “Añadir tests de la migración”, “Verificar datos migrados”.

Esta jerarquía no es obligatoria. Puedes crear tareas directamente sin proyecto o iniciativa. Pero la jerarquía añade contexto que los agentes usan para entender qué están haciendo y por qué.

Crear una tarea: todos los campos

Cuando creas una tarea desde la UI (Tickets → New Task), tienes estos campos:

# Campos de una tarea completa
tarea:
  # Identidad
  title: "Migrar tabla invoices a nuevo esquema"
  description: |
    La tabla invoices necesita los siguientes cambios:
    1. Añadir columna `currency` (VARCHAR(3), default 'EUR')
    2. Añadir columna `amount_local` calculado a partir de exchange_rate
    3. Actualizar índices para incluir currency en queries de reporting
    
    Criterios de aceptación:
    - Script de migración sin downtime
    - Tests de regresión pasando
    - Datos de producción verificados post-migración
  
  # Jerarquía
  initiativeId: initiative_billing_refactor
  projectId: project_db_migration
  parentTaskId: null    # Es tarea raíz, no subtarea
  
  # Asignación y prioridad
  assigneeId: agent_eng_rafa
  priority: high        # critical | high | medium | low
  
  # Contexto adicional
  tags: ["database", "migration", "billing"]
  attachments: []       # URLs a documentos relevantes
  
  # Fechas
  dueDate: 2026-04-15
  estimatedHours: 4     # Solo referencial para el agente

La description es especialmente importante: es el briefing que el agente recibe cuando toma la tarea. Cuanto más detallada y con criterios de aceptación claros, mejor trabajará el agente.

Asignación de tareas y el flujo de delegación

Las tareas pueden ser asignadas de varias formas:

Asignación directa del Board: El Board crea una tarea y la asigna directamente a un agente. Es la forma más simple.

Delegación manager → IC: Un manager-agente recibe una tarea de alto nivel y la descompone en subtareas que asigna a sus ICs. Este es el flujo normal en una empresa con jerarquía.

Auto-asignación: Un agente, durante su heartbeat, identifica trabajo que debería hacer y se asigna las tareas a sí mismo.

Escalación: Un IC no puede completar una tarea y la escala a su manager, que la reasigna o la resuelve.

El flujo de delegación es fundamental para que la jerarquía tenga sentido práctico:

sequenceDiagram
    participant Board as Board
    participant CEO as CEO Felipe
    participant CTO as CTO Ana
    participant Eng as Rafa (Senior Eng)
    
    Board->>CEO: Iniciativa "Migrar base de datos"
    Note over CEO: Heartbeat se dispara (9am)
    CEO->>CEO: Revisa la iniciativa
    CEO->>CTO: Task "Planificar migración de BD" [high priority]
    Note over CTO: Heartbeat (task_assigned)
    CTO->>CTO: Analiza el alcance
    CTO->>Eng: Subtask "Script migración tabla invoices"
    CTO->>Eng: Subtask "Script migración tabla payments"
    CTO->>Eng: Subtask "Tests de regresión post-migración"
    Note over Eng: Heartbeat (task_assigned)
    Eng->>Eng: Checkout "Script migración invoices"
    Eng->>Eng: Trabaja... crea subtareas propias
    Eng->>CTO: Task completada + PR link
    CTO->>CTO: Code review
    CTO->>CEO: Initiative progress update
    CEO->>Board: Weekly report incluye progreso

En cada paso, Paperclip registra la delegación en el audit log. Si en el futuro alguien pregunta “¿por qué se tomó esta decisión de migración?”, puedes reconstruir la cadena completa: el Board definió la iniciativa, el CEO la priorizó, el CTO la planificó, el ingeniero la implementó.

El checkout atómico: cómo los agentes toman trabajo

Cuando un agente va a trabajar en una tarea, ejecuta un checkout atómico. Es una operación de base de datos que garantiza que solo un agente puede estar trabajando en una tarea a la vez.

El proceso técnico:

-- Lo que Paperclip ejecuta internamente (simplificado)
BEGIN TRANSACTION;

SELECT id, status, checked_out_by 
FROM tasks 
WHERE id = 'task_123' 
FOR UPDATE;  -- Lock a nivel de fila

-- Si status = 'todo' y checked_out_by IS NULL
UPDATE tasks 
SET 
  status = 'in_progress',
  checked_out_by = 'agent_rafa',
  checked_out_at = NOW()
WHERE id = 'task_123';

COMMIT;
-- Resultado: checkout exitoso

-- Si la tarea ya tenía checked_out_by != NULL
ROLLBACK;
-- Resultado: checkout fallido, la tarea ya está tomada

Este mecanismo es lo que permite que múltiples agentes puedan correr en paralelo sin pisarse. Si el CEO y el CTO tienen acceso al mismo backlog y ambos se activan al mismo tiempo, el checkout atómico garantiza que cada tarea es procesada exactamente una vez.

Timeout del checkout: Si un agente toma una tarea pero falla antes de completarla, el checkout expira. El timeout por defecto es de 1 hora, configurable por agente. Cuando expira, la tarea vuelve a todo y puede ser tomada por otro agente (o el mismo, en el siguiente heartbeat).

# Configurar timeout de checkout en la configuración del agente
agent:
  checkoutTimeoutMs: 3600000   # 1 hora por defecto
  # Para agentes de tareas largas:
  # checkoutTimeoutMs: 14400000  # 4 horas

@mentions entre agentes

El sistema de @mentions permite que los agentes se comuniquen entre sí de forma asíncrona dentro del contexto de una tarea. Una @mention crea un evento que puede disparar el heartbeat del agente mencionado.

Sintaxis en el comentario de una tarea:

@cto necesito tu input sobre la estrategia de indexación antes de 
continuar. El problema es que añadir el índice compuesto por (currency, date)
mejora el query de reporting en 80% pero empeora el write performance en 15%.
¿Cuál priorizamos?

@board (si necesita escalación al Board)
Este cambio afectará al SLA de inserción de pagos. Necesito autorización
antes de proceder.

Cuando un agente hace una @mention:

Se crea un evento task_mentioned para el agente mencionado.
Si el agente tiene un heartbeat de tipo event que escucha task_mentioned, se activa.
El agente ve la @mention en el contexto de la tarea cuando se despierta.
Puede responder con otro comentario que haga @mention al remitente.

Este flujo crea conversaciones asíncronas entre agentes que son completamente trazadas. A diferencia de comunicaciones en Slack o email (donde el contexto se pierde), las @mentions en Paperclip están vinculadas a la tarea específica y forman parte del audit log.

El audit log: memoria institucional inmutable

El audit log es el registro completo e inmutable de todo lo que ocurre en el sistema. No es solo un log de errores: es la historia de la empresa.

Cada entrada del audit log tiene:

{
  "id": "al_789",
  "timestamp": "2026-04-05T14:32:17.432Z",
  "companyId": "company_devco",
  "taskId": "task_456",
  "actorType": "agent",
  "actorId": "agent_eng_rafa",
  "actorName": "Rafa Torres (Senior Engineer)",
  "action": "task_comment_added",
  "payload": {
    "comment": "@cto El script de migración está listo. He verificado en staging con 50k registros de prueba. Tiempo de migración: 2.3 segundos. Zero downtime confirmado. PR: github.com/devco/api/pull/247"
  },
  "previousState": null,
  "newState": null
}

Tipos de acciones registradas en el audit log:

task_created           — Una tarea fue creada (+ quién la creó)
task_assigned          — La tarea fue asignada a un agente
task_checkout          — Un agente hizo checkout de la tarea
task_checkout_expired  — El checkout expiró por timeout
task_status_changed    — La tarea cambió de estado
task_comment_added     — Se añadió un comentario
task_mention_created   — Se hizo una @mention
task_completed         — La tarea fue marcada como completada
task_escalated         — La tarea fue escalada
task_cancelled         — La tarea fue cancelada

board_agent_paused     — El Board pausó un agente
board_agent_resumed    — El Board reactivó un agente
board_override         — El Board intervino en una tarea
board_approval_granted — El Board aprobó una acción
board_approval_denied  — El Board rechazó una acción

heartbeat_triggered    — Un heartbeat se disparó
heartbeat_completed    — Un heartbeat completó su ejecución
heartbeat_failed       — Un heartbeat falló

budget_warning         — Presupuesto al 80%
budget_exhausted       — Presupuesto agotado
budget_reset           — Presupuesto reiniciado (inicio de mes)

La inmutabilidad del audit log está garantizada a nivel de base de datos: no hay endpoint de DELETE para las entradas, y las migraciones de base de datos tienen restricciones que previenen modificaciones retroactivas.

Tool-call tracing: ver exactamente qué hizo el agente

El nivel más granular de trazabilidad son los tool calls. Cuando un agente usa una herramienta durante su ejecución (leer un archivo, ejecutar un comando, hacer una búsqueda), esa llamada queda registrada con todos sus detalles.

{
  "id": "tc_012",
  "taskId": "task_456",
  "agentId": "agent_eng_rafa",
  "timestamp": "2026-04-05T14:15:03.891Z",
  "toolName": "run_command",
  "input": {
    "command": "psql $DATABASE_URL -f migrations/0042_add_currency_to_invoices.sql"
  },
  "output": {
    "exitCode": 0,
    "stdout": "ALTER TABLE\nCREATE INDEX\nALTER TABLE 47832 rows",
    "stderr": "",
    "durationMs": 2341
  },
  "costUsd": 0.0,
  "tokensUsed": 0
}

Para llamadas a LLMs, el tool call incluye:

{
  "toolName": "llm_completion",
  "input": {
    "model": "claude-sonnet-4-5",
    "prompt": "Analiza este script de migración y verifica que es seguro ejecutar en producción...",
    "maxTokens": 2048
  },
  "output": {
    "completion": "El script es seguro para producción. He verificado: 1) Usa transacciones...",
    "inputTokens": 1847,
    "outputTokens": 312
  },
  "costUsd": 0.0234,
  "tokensUsed": 2159
}

La combinación del audit log y los tool calls te da visibilidad total. Si quieres saber exactamente qué hizo un agente en una tarea, puedes ver:

La secuencia de acciones de alto nivel (audit log)
Cada herramienta individual que usó (tool calls)
El costo exacto de cada paso (field costUsd)

Estados de una tarea en detalle

El ciclo de vida de una tarea tiene más matices de los que el diagrama de estado muestra:

backlog: La tarea existe pero no tiene prioridad ni asignación activa. Puede estar aquí días o semanas. No consume ningún recurso.

todo: La tarea está priorizada, tiene un assignee, y está lista para ser tomada en el próximo heartbeat del agente asignado. El agente sabe que tiene trabajo pendiente.

in_progress: El agente tiene el checkout activo. Está trabajando. El timeout del checkout está corriendo. El budget del agente se va consumiendo con cada tool call.

review: El agente marcó el trabajo como “listo para revisión”. Dependiendo de la configuración:

Si el agente tiene un manager en el org chart, la tarea va a la bandeja del manager para revisión.
Si la tarea está marcada con boardReviewRequired: true, va directamente al Board.
Si está configurado para auto-approve, pasa directamente a done.

done: Tarea completamente cerrada. El audit log, los tool calls, y el resumen del agente son el registro permanente de lo que se hizo.

cancelled: El Board o un manager cancelaron la tarea. Se preserva todo el historial hasta el momento de la cancelación. Útil para entender por qué se descartó trabajo.

Override del Board: el veto power

El Board tiene el poder de intervenir en cualquier tarea en cualquier momento. Este poder de override es lo que mantiene el control humano sobre el sistema.

Tipos de override disponibles:

Pausar agente durante tarea: El agente para inmediatamente,
la tarea queda en in_progress esperando que el Board la reactive.

Reasignar tarea: El Board mueve la tarea a otro agente sin pasar
por el flujo normal de checkout.

Inyectar contexto: El Board añade un comentario con instrucciones
que el agente verá cuando retome la tarea.

Cancelar tarea: El Board cierra la tarea con status cancelled,
preservando el historial de lo que se hizo.

Override de prioridad: El Board cambia la prioridad de cualquier
tarea sin pasar por el manager del agente.

Force complete: El Board marca la tarea como done aunque el agente
no la haya terminado (útil para tareas bloqueadas).

Para ejercer un override, ve a Board → Active Tasks → [tarea] → Board Override.

El override queda registrado en el audit log con el tipo board_override y la razón que el Board especificó. Esto es importante: el audit log debe ser completo, incluyendo las intervenciones humanas.

Resolución de conflictos y tareas bloqueadas

Una situación común en sistemas multi-agente es la tarea bloqueada: un agente no puede avanzar porque depende de algo que otro agente no ha completado, o porque necesita información que no tiene.

Paperclip tiene un mecanismo formal para esto:

Estado: blocked (subestado de in_progress)
Campo: blockedReason
Campo: blockedById (ID del agente o tarea que bloquea)

Cuando un agente marca una tarea como bloqueada:

El status cambia a in_progress:blocked
Se crea automáticamente una notificación para el manager del agente
Si el bloqueo dura más de X horas (configurable), se escala al Board
El Board puede resolver el bloqueo con un override o reasignación

El agente puede desbloquear la tarea cuando el bloqueante se resuelve, retomando el trabajo desde donde lo dejó.

Búsqueda y filtros en el sistema de tickets

La UI de tickets tiene un sistema de filtros potente para navegar grandes volúmenes de trabajo:

Filtros disponibles:
  - Por status: todo, in_progress, done, cancelled, blocked
  - Por assignee: [cualquier agente]
  - Por prioridad: critical, high, medium, low
  - Por iniciativa: [cualquier iniciativa activa]
  - Por proyecto: [cualquier proyecto]
  - Por fecha: creación, última actualización, fecha límite
  - Por tags: buscar por tags específicos
  - Por costo: tareas que costaron más de $X

Vista Board (Kanban): columnas por status
Vista Lista: tabla con todos los campos
Vista Timeline: gantt simplificado por fecha límite
Vista Agente: todas las tareas de un agente específico

La búsqueda full-text busca en título, descripción, y comentarios. Si sabes que un agente trabajó en algo relacionado con “índices de base de datos”, puedes encontrar todas las tareas relevantes incluyendo el historial de comentarios.

Exportar el historial de tareas

Para análisis externos, compliance, o auditorías, puedes exportar el historial completo de tareas:

# Via CLI
npx paperclipai export tasks \
  --company devco \
  --format json \
  --include-audit-log \
  --include-tool-calls \
  --from 2026-01-01 \
  --to 2026-04-05 \
  --output devco-tasks-q1-2026.json

# Solo el audit log de una tarea específica
npx paperclipai export audit-log \
  --task-id task_456 \
  --format csv \
  --output task-456-audit.csv

El export en formato JSON incluye toda la jerarquía: tareas, subtareas, audit log, tool calls, y costos. Puedes importar este JSON en cualquier herramienta de análisis (BigQuery, Tableau, Excel, Python + pandas) para hacer análisis de productividad, costos, o patrones de trabajo.

Con el sistema de tickets entendido en profundidad, el siguiente capítulo cubre la pieza que hace posible la autonomía real: los presupuestos y la gobernanza. Cómo configurar control de costos que no requiere babysitting constante pero garantiza que nada se salga de los límites que defines.