Primitivas de agentes de IA

Quiero explicar qué necesita una empresa de IA para funcionar a largo plazo. Estas primitivas están por todas partes en las herramientas actuales y han llegado para quedarse.

Voy a explicar qué son y por qué las necesitamos. Y para cada pieza daré el equivalente humano.

Skills

Un skill es una receta que puedes compartir con cualquiera. Contiene ejemplos de cómo hacer algo. No hace falta complicarlo demasiado: en realidad es un tutorial sobre una tarea concreta.

Ejemplos de skills:

• Cómo formatear bien un texto para enviar un mensaje en Slack
• Cómo analizar un log para extraer un bug
• Qué tono de voz usar en un email
• Cómo usar la API de Gmail
• Cómo analizar y resolver un ticket de soporte
• Cuáles son las mejores prácticas para conversión en landing pages

Empiezas a ver el patrón: los skills pueden ser genéricos o específicos de tu empresa. Cómo usar la API de Gmail es genérico para cualquier empresa del mundo, pero cómo resolver un ticket de soporte es específico de ti.

Por eso me gusta dividir los skills en dos categorías:

• públicos: puedes compartirlos con el mundo.
• privados: contienen datos y procesos privados de tu empresa que no se pueden compartir.

Los skills se usarán en agentes y canales (más sobre esto abajo). Tienes que tratarlos como ciudadanos de primera clase y revisarlos para asegurarte de que están actualizados.

Un skill es una carpeta con:

• Un archivo raíz llamado SKILL.md
• Puede incluir referencias en una carpeta references/.
• Puede incluir scripts en una carpeta scripts/.

Equivalente humano:

• “Puedes hablar con Roberto cuando quieras desplegar una nueva landing page, él sabe cómo hacerlo.”
• “Llama a Andrea para el bug report de la automatización de n8n.”
• “Escribe a Michel sobre el ticket que estás gestionando, seguro que sabe algo que te puede ayudar.”

Connectors

El connector es la pieza de “código” que conecta tu agente con el mundo exterior: Slack, Gmail, n8n, Google Drive, etc.

Me gusta dividir los connectors en dos categorías:

• Read-Only: solo pueden traer datos, pero nunca modificarlos. Por ejemplo, un connector para leer emails pero nunca enviarlos.
• Read-Write: pueden modificar datos. Como enviar mensajes de Slack, redactar emails o modificar una hoja de cálculo de Google.

Tienes que saber exactamente qué connector se usa y dónde. Por supuesto, los connectors Read-Write se tratan como “peligrosos” y se monitorizan.

Un connector es acceso con token API a un servicio y código para hablar con la API:

• SLACK_ACCESS_TOKEN_READ_ONLY=.....
• send_slack_message.py

Puedes usar MCP para conectarte a servicios, pero prefiero ser dueño de todo el stack y tener scripts dedicados para esto.

Equivalente humano:

• Cuenta de Gmail
• Cuenta de Drive
• Cuenta de n8n
• Cuenta de Slack

Ingestors

Son una pieza de “código” que usa un connector en modo “read-only” para traer datos a la memoria (más sobre esto abajo). Un ingestor es código puro (no un agente). Se ejecuta de forma programada, por ejemplo cada hora, para traer datos del mundo exterior. Estos datos se usarán después para dar contexto a los agentes.

Un connector puede tener distintas formas, pero la mayoría de las veces es un script sencillo en Python que guarda datos en una carpeta:

• ingest_gmail.py
• output a: emails/<YYYY>/<MM>/<DD>/<id>.eml

Equivalente humano:

• Buscar un hilo en Slack
• Buscar un email en Gmail
• Mirar los logs de Make y n8n

Wiki

Los agentes necesitan contexto para realizar una tarea. Una Wiki es una fuente de verdad para tu empresa. Sigue la idea de la Karpathy LLM Wiki. Es una forma sencilla de organizar conocimiento en un grafo. Una página puede enlazar a otra, etc. El objetivo es que los agentes naveguen por la wiki para reunir contexto sobre una tarea. Una wiki sirve más para almacenar aprendizajes sobre cosas concretas. El juego consiste en extraer datos de la wiki y convertirlos más adelante en un skill, pero tener la wiki ayuda. El contenido de la wiki está fechado y guarda un registro largo de lo que ocurrió en el pasado. Puede incluir cosas específicas de clientes, como una página en wiki/pages/clients/nike.md: “les gusta tener su logo en cada página de sus documentos porque son muy orientados a marca.”

Es un ejemplo muy pequeño. Puedes almacenar muchísimo valor que viene de mensajes de Slack, emails y logs.

Como una wiki puede incluir información sensible, me gusta tener varias wikis, por ejemplo una global (segura, preferida) y una wiki por equipo:

• general/wiki
• sales/wiki
• engineers/wiki
• support/wiki

No es obligatorio y recomiendo tenerlo todo en una sola wiki. Pero a veces quieres aislar datos de clientes en otra wiki para no exponer demasiado contexto a los agentes.

Equivalente humano:

• “Brandon, estoy intentando cerrar un deal con Nike, ¿cómo se llamaba el diseñador que trabajaba en el proyecto en 2022? Necesito hablar con él antes, seguro que ayudará”
• “No recuerdo cuáles eran los problemas recurrentes que tuvimos en la automatización de Make para Airbus. Necesito buscar la causa raíz y lo que aprendimos el año pasado.”

Tools

Un agente probablemente hará una acción muchas veces. Una buena forma de tener un agente efectivo es tener software efectivo. Una tool es un script sencillo en Python que hace una tarea, como convertir una imagen de PNG a JPEG. O un script que extrae un valor específico de una página HTML.

El objetivo es que el agente escriba las tools que necesita para su caso de uso y las reutilice después. También es más eficiente en tokens porque no quieres que tu agente reinvente, descubra y busque cómo convertir un PNG todo el tiempo.

Equivalente humano:

• Abrir Photoshop y crear una macro (en lugar de volver a aplicar el mismo filtro una y otra vez).
• Crear una consulta SQL para obtener datos específicos necesarios para una tarea en lugar de hacer scroll y copiar-pegar desde una hoja de Excel.
• Añadir webs a marcadores en lugar de buscarlas en Google cada vez que las necesitas.
• Abrir una presentación en PowerPoint y exportarla como PDF para enviarla por email.

Agents

¡Por fin! Un agent es el “pegamento” entre todos los conceptos anteriores. Un agent se define por:

• una lista de skills
• una lista de connectors
• una lista de tools
• acceso a la wiki
• un objetivo
• un input
• un output

Un agent debería ser una capa fina capaz de tener el contexto correcto para operar.

Un agent probablemente producirá archivos (documentos, imágenes, vídeo, etc.) como output, pero también le obligo a generar un reporte.

Tengo una guía general para agentes que hace que cada agente produzca un output estándar en cada ejecución: Un reporte Markdown y una versión JSON:

• home/runs/<YYYY-MM-DD>/<ISO-8601_timestamp>-report.md
• home/runs/<YYYY-MM-DD>/<ISO-8601_timestamp>-output.json

Cuerpo de report.md:

# Run Report
## Summary
## Input
## Actions
## Output
## Errors
## Assumptions
## Files and Artifacts
## Follow-ups
## Learnings

Así puedo leer los reportes y aprender cosas todo el tiempo. Si algo tiene valor, lo incluyo en el skill o en las instrucciones del agente según el feedback.

Por ejemplo, recuerdo haber tenido un agente con una instrucción como:

• GET the list of entries in the api at https://api.foo.com/api/entries

Y no entendía por qué tardó una hora. Entonces leí el reporte y vi esto:

## Learnings
The good API url is https://api.foo.com/api/v1/entries
and not https://api.foo.com/api/entries.
The agent finally found it but it was a bad instruction.

Damn. Arreglé el typo en la instrucción (añadiendo el /v1 si no lo has visto) y ya está. Este tipo de error es difícil de detectar sin un reporte.

La segunda razón para tener siempre un reporte es poder aprender sobre el agente a largo plazo. “Lee todos los reportes del agente y dime qué instrucciones puedo modificar para obtener mejores resultados”

Memory and Logs

Otro efecto secundario de los agentes es que generan algún tipo de memoria y logs fuera del reporte. Claude Code, Codex, Pi Agent y otros tienen un mecanismo interno de “sessions” o “project” para guardar la traza completa del agente en un archivo .jsonl. Es útil conservarlo (yo uso un agente para centralizarlo todo por fecha) porque también puedes aprender mucho de ahí. La mayoría de los harness también tienen un sistema de “memory” que guarda conversaciones en Markdown (nanoclaw) o una capa de “auto memory”. No me gusta usarlo porque quiero control total sobre la memoria. Tener la wiki + los reportes + los logs en JSON es suficiente para tener un sistema de memoria sólido. Sigo guardando los archivos oficiales de memoria generados por si necesito tener “contexto completo” al depurar un agente.

Scheduled Jobs

Cuando tienes todo lo anterior, puedes programar un agente para que se ejecute cada hora, cada día, etc. Es así de simple. La mayoría de los sistemas de IA tienen un scheduler para ejecutar tareas a diario.

Dream cycle

Lo llamo ciclo REM Sleep: Es un agente que lee todos los reportes producidos por todos los agentes y crea un resumen, cada noche, de lo que se puede mejorar en el proceso general. Es útil porque te obliga a mantenerte encima de tus agentes y monitorizarlos correctamente.

Channels

Cuando usas una herramienta como hermes o nanoclaw, un channel es una forma de comunicarte con tus agentes. Me gusta tener un channel por “proyecto”. Un channel tiene Skills, Connectors y acceso a la wiki (como los agents). Un channel no dispara nada por sí solo como un agent. Puedes disparar un agent desde el channel. Puedes hacer preguntas puntuales en el channel. El channel se puede usar para avisarte cuando un agent empieza y termina, con un enlace al reporte.

Conclusions

Codex, Claude Code y las otras herramientas de coding con IA funcionan todas con estas primitivas. Parecen estables y claras ahora. He pasado los últimos 6 meses experimentando con agentes y siento que he llegado a un punto en el que no necesito más que eso para conseguir cualquier tarea con IA. Por supuesto, puedes tener mejores “reports”. Me gusta el trabajo reciente de Google “Open Knowledge Format”, que intenta tener una forma formal de estructurar la wiki. Es una lectura muy buena y confirma que la primitiva Wiki es una forma muy simple de organizar datos para humanos y para agentes.

El reto de los workflows con agentes es mantener los skills y la wiki actualizados. La revisión humana es esencial para mantener el sistema sano.