Cómo dirigir un ejército de agentes: bitácoras, control, ClickUp y CRM

Módulo: Práctica profesional | Tiempo: ~30 min de teoría + 40 min de práctica

Lo esencial

Cuando tienes un solo agente, todo está claro. Cuando tienes 10 o más, dejas de saber quién hizo qué, cuánto costó y por qué ayer algo salió mal.

🎨 Imagínalo así: un restaurante con un solo cocinero frente a un restaurante con un equipo de 15 personas. Al cocinero lo controlas con la mirada. A un equipo de 15, solo con la comanda, los indicadores y los turnos. Sin eso hay caos: dos cocineros preparan el mismo platillo, un tercero está parado y el chef no sabe qué pasa en la cocina.

Esta lección trata de cómo poner orden en tu ejército de agentes: auditoría, bitácoras, tableros de estado e integración con ClickUp y con un CRM.

Conceptos clave

• Por qué la "caja negra" es la raíz de todos los problemas con agentes
• Tres niveles de registro: archivo, base de datos, herramienta externa de gestión de proyectos
• ClickUp MCP: el agente crea tareas y actualiza su estado por sí solo
• Notion como base de conocimiento de los resultados de los agentes
• Integración con el CRM: terminó el trabajo, actualizó la ficha del cliente
• STATUS.md: un tablero vivo que Claude actualiza solo

Teoría

El problema de la "caja negra"

Sin gestión, los agentes funcionan como cajas negras: los lanzas, hacen algo y te regresan un resultado. ¿Qué pasó adentro? ¿Cuál arrancó primero? ¿Por qué uno se quedó colgado? ¿Cuánto dinero se gastó durante la noche?

🎨 Imagínalo así: un taxi sin taxímetro y sin ruta. ¿Llegaste? Perfecto. ¿Cuánto costó? Quién sabe. ¿Por qué llegó tarde? Misterio. ¿Se puede repetir exactamente el mismo recorrido? No.

Cinco síntomas de la "caja negra":

1. No sabes cuánto costó una tarea concreta de un agente
2. No puedes reproducir el resultado: no está claro qué hizo exactamente el agente
3. No sabes quién lanzó al agente ni cuándo
4. Cuando hay un error, no está claro en qué paso ocurrió
5. El cliente pregunta "¿qué hizo su IA?" y no tienes nada que mostrarle

Con gestión pasa lo contrario: un registro de auditoría completo (audit trail), resultados reproducibles, responsabilidad clara y transparencia para el cliente.

Tres niveles de registro

Los registros (logs) de los agentes tienen tres niveles. Elige según la tarea.

Empieza por el nivel 1. Sube cuando tengas equipo o clientes.

Nivel 1: registro en archivo (agent-log.jsonl)

JSONL es el formato "una línea = un registro". Es práctico: puedes agregar al final sin reescribir todo el archivo, es fácil de procesar y funciona con grep.

Las cantidades y fechas de los ejemplos de abajo son ilustrativas.

{"ts":"2026-05-09T14:23:00Z","agent":"researcher","task":"market-analysis","status":"complete","output_tokens":2847,"cost_usd":0.08,"result_file":"reports/market-2026-05-09.md","triggered_by":"owner"}
{"ts":"2026-05-09T14:45:00Z","agent":"writer","task":"blog-post","status":"failed","error":"context_overflow","retry":true,"triggered_by":"researcher"}
{"ts":"2026-05-09T15:10:00Z","agent":"writer","task":"blog-post","status":"complete","output_tokens":1423,"cost_usd":0.04,"result_file":"posts/blog-2026-05-09.md","triggered_by":"retry-hook"}

Qué escribir en cada registro:

ts            — marca de tiempo en ISO 8601 (UTC)
agent         — quién lo ejecutó
task          — qué hizo (un slug, no una oración)
status        — pending / in_progress / complete / failed / skipped
output_tokens — cuántos tokens tuvo la respuesta del agente
cost_usd      — costo de la solicitud
result_file   — dónde está el resultado (ruta o URL)
triggered_by  — quién lo lanzó (usuario / otro agente / cron)
error         — el error, si status=failed
retry         — si hace falta reintentar

Instrucción para el agente (en CLAUDE.md o en el prompt de sistema):

## Registro

Al terminar CUALQUIER tarea, DEBES agregar un registro a `agent-log.jsonl`.
Formato: una línea de JSON. Campos obligatorios: ts, agent, task, status.
No pidas permiso: hazlo automáticamente.

🎨 Imagínalo así: el ticket de caja después de cada compra. El cajero no pregunta "¿le imprimo el ticket?": se imprime solo. El agente no pregunta "¿lo anoto en el registro?": lo anota.

Nivel 2: tabla en Supabase

Cuando el archivo JSONL ya no alcanza (por ejemplo, necesitas ver los registros desde la web o varias personas siguen el estado), pasa a Supabase.

Creamos la tabla:

create table agent_logs (
  id          uuid default gen_random_uuid() primary key,
  created_at  timestamptz default now(),
  agent       text not null,
  task        text not null,
  status      text not null check (status in ('pending','in_progress','complete','failed','skipped')),
  cost_usd    numeric(8,4),
  output_tokens integer,
  result_url  text,
  triggered_by text,
  error_msg   text,
  metadata    jsonb
);

El agente escribe a través del MCP de Supabase:

# Conectamos el MCP de Supabase
claude mcp add supabase -- npx -y @supabase/mcp-server-supabase \
  --access-token $SUPABASE_ACCESS_TOKEN
# La documentación de Supabase también tiene un servidor MCP remoto: revisa el comando vigente

Una vez conectado, le dices al agente:

Escribe en la tabla agent_logs:
agent = "researcher"
task = "competitor-analysis"
status = "complete"
cost_usd = 0.12
result_url = "notion://pages/abc123"

Claude lo traduce a un INSERT de SQL y lo ejecuta directamente a través del MCP.

Nivel 3: ClickUp MCP, el agente gestiona las tareas

ClickUp es una herramienta de gestión de proyectos. El agente puede crear tareas ahí, actualizar su estado y escribir comentarios. El cliente ve el avance en tiempo real, en una herramienta que ya conoce.

Instalación del MCP de ClickUp:

# Opción 1: a través de Composio (arranque rápido). El formato de la dirección de Composio ha cambiado, revisa su documentación
claude mcp add --transport http clickup-composio \
  https://mcp.composio.dev/clickup?apiKey=YOUR_COMPOSIO_KEY

# Opción 2: el MCP oficial de ClickUp (revisa su estado y dirección en la documentación de ClickUp)
claude mcp add --transport http clickup \
  https://mcp.clickup.com/mcp

Una vez conectado, el agente recibe herramientas (los nombres dependen del servidor; estos son ejemplos):

• create_task: crear una tarea
• update_task_status: cambiar el estado
• add_comment: agregar un comentario
• get_tasks: obtener la lista de tareas

Ejemplo de flujo: el agente investigador termina un análisis de mercado.

El agente entregó el reporte →
El agente creó la tarea en ClickUp "Market Analysis — Ecuador Real Estate 2026-05" →
Adjuntó el resultado →
Puso status = Done →
Creó la siguiente tarea "Write blog post based on research" →
Te llegó una notificación en ClickUp

Instrucción para el agente:

## Integración con ClickUp

Al terminar cada tarea:
1. Cambia el estado de la tarea en ClickUp a "Done" (usa update_task_status)
2. Agrega un comentario con un resumen breve (2-3 líneas)
3. Si hay un siguiente paso, crea una tarea nueva
4. Listas de ClickUp: Research → List ID 901234, Writing → List ID 901235

🎨 Imagínalo así: ClickUp es el tablero de tareas de la oficina. Antes el gerente movía las notas adhesivas a mano. Ahora el agente las mueve solo y el gerente solo mira el tablero.

STATUS.md: un tablero vivo

Un archivo STATUS.md que Claude actualiza después de cada tarea terminada:

# STATUS.md — AI Operations Dashboard

> Actualizado: 2026-05-09 15:47 UTC

## Agentes activos

| Agente | Tarea | Estado | Costo | Actualizado |
|-------|--------|--------|-----------|-----------|
| researcher | market-analysis Ecuador | ✅ Done | $0.08 | 14:23 |
| writer | blog-post bienes raíces | 🔄 In Progress | $0.04 | 15:10 |
| designer | thumbnail YouTube | ⏳ Queued | — | — |
| deployer | production deploy | ❌ Failed | $0.02 | 15:30 |

## Gastado hoy

- Total: $0.14
- Agentes lanzados: 4
- Con éxito: 2 / Con error: 1 / En curso: 1

## Últimos errores

- **deployer** 15:30 — context_overflow durante el despliegue. Retry scheduled 16:00.

Agrega al CLAUDE.md del agente: "Después de cada tarea terminada, actualiza STATUS.md: tu fila + el resumen del día."

Notion MCP: base de conocimiento

ClickUp = para tareas y procesos. Notion = para conocimiento y resultados.

Cada agente investigador escribe sus conclusiones estructuradas en Notion. Después, otro agente las lee y no repite el mismo trabajo.

# Servidor MCP remoto oficial de Notion (revisa la dirección en la documentación de Notion)
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Al conectarlo, Notion te pedirá iniciar sesión y dar acceso a las páginas que necesites

Instrucción para el agente:

## Notion: guardar resultados

Después de cada investigación, crea una página en la base "Research":
- Título: [Tema] — [Fecha]
- Etiquetas: tipo de investigación, región, proyecto
- Contenido: conclusiones clave (3-5 puntos), fuentes, qué tan confiables son los datos
- Enlace al reporte completo

Antes de empezar una investigación nueva, busca primero en Notion.
Si ya existe un trabajo parecido, úsalo.

🎨 Imagínalo así: la wiki de una empresa. Cuando alguien deja la empresa, su conocimiento no se va con él. Cuando una sesión del agente "se va", el conocimiento se queda en Notion.

Registro de auditoría con hashes de Git

El registro de auditoría más confiable son los commits de Git.

{
  "ts": "2026-05-09T14:23:00Z",
  "agent": "researcher",
  "task": "competitor-analysis",
  "git_before": "abc123def",
  "git_after": "456789ghi",
  "files_changed": ["reports/competitors-2026-05-09.md"],
  "cost_usd": 0.08,
  "status": "complete",
  "duration_sec": 127
}

git diff abc123 456789 te muestra cada línea que cambió el agente. Reproducibilidad completa.

Integración con el CRM (HubSpot / Pipedrive)

El agente terminó un análisis para un cliente → en el CRM aparece un registro automáticamente.

# HubSpot a través de Composio (revisa el formato de la dirección en la documentación de Composio)
claude mcp add --transport http hubspot \
  https://mcp.composio.dev/hubspot?apiKey=YOUR_KEY

Instrucción para el agente:

## Actualización del CRM

Si la tarea tiene que ver con un cliente (hay client_id):
1. Agrega una nota en HubSpot: "[Agente] terminó [tarea]. Resultado: [una línea]"
2. Actualiza el campo "Last AI Action" con la fecha
3. Si hay un siguiente paso para el ejecutivo, crea una tarea en el CRM

🎨 Imagínalo así: antes, el ejecutivo de ventas entraba al CRM a mano después de cada llamada. Ahora el agente actualiza el CRM solo. El ejecutivo ve el estado actual sin trabajo manual.

Modelo de madurez: por dónde empezar

Nivel 1: agent-log.jsonl (15 min)
↓
Nivel 2: STATUS.md (30 min)
↓
Nivel 3: ClickUp MCP (2 horas)
↓
Nivel 4: base de conocimiento en Notion (2-3 horas)
↓
Nivel 5: integración con el CRM (3-4 horas)
↓
Nivel 6: Supabase + registro de auditoría completo (1 día)

Empieza hoy por el nivel 1.

Práctica

1. Crea agent-log.jsonl y agrega la instrucción para el agente en CLAUDE.md
2. Crea STATUS.md con la tabla de agentes
3. Lanza cualquier agente y comprueba que los dos archivos se actualizaron
4. (Opcional) Conecta el MCP de ClickUp si tienes cuenta
5. (Opcional) Conecta el MCP de Notion para guardar resultados

# Paso 1
touch agent-log.jsonl

# Paso 2
cat > STATUS.md << 'EOF'
# STATUS.md

> Actualizado: a mano

## Agentes activos

| Agente | Tarea | Estado | Costo |
|-------|--------|--------|-----------|
| — | — | — | — |
EOF

# Paso 3: revisión después de que trabaje el agente
tail -5 agent-log.jsonl

Herramientas y recursos

• ClickUp MCP: servidor oficial de ClickUp (revisa su estado en la documentación)
• Composio: cientos de integraciones a través de un solo MCP
• Notion MCP: documentación del MCP oficial de Notion
• Supabase MCP: para bases de datos
• HubSpot a través de Composio: integración con el CRM

Conclusiones clave

Los agentes sin bitácora son cajas negras. Empieza con agent-log.jsonl (15 minutos): una línea de JSON después de cada tarea.

STATUS.md es un tablero vivo que el agente actualiza solo. Ves el estado de todo tu ejército de un vistazo.

ClickUp MCP: el agente crea tareas y actualiza su estado por sí solo. El cliente ve el avance en su propia herramienta.

Notion es la memoria entre sesiones. Pagas una investigación una vez, no cada vez de nuevo.

Siguiente lección

→ Modelos de IA locales: Ollama, LM Studio e IA privada