La mayoría de los tutoriales sobre agentes de IA empiezan con la configuración de herramientas. Conecta este servidor MCP. Registra esta skill. Configura estos prompts.
Luego los usuarios se preguntan por qué su agente “Director de Marketing” envía correos a través de SendGrid un día y por Mailgun al siguiente. O por qué el “Analista SEO” a veces consulta Google Analytics, otras veces Search Console, y a veces simplemente inventa métricas.
Los agentes son teóricamente capaces. Tienen herramientas de correo. Tienen acceso a analítica. Pero no funcionan de manera confiable.
Esto es lo que aprendimos al construir 14 Characters de IA para TeamDay: el problema no son las herramientas. El problema es la metodología.
La trampa de la abstracción
El ecosistema de agentes de IA adora las taxonomías. Herramientas vs. servidores MCP vs. skills vs. plugins vs. prompts. Los desarrolladores pasan horas debatiendo: ¿debería el correo electrónico ser una herramienta MCP o una skill con script bash?
Desde la perspectiva del usuario de negocio, estas distinciones no tienen ningún sentido.
Cuando alguien le pide a su Director de Marketing que “envíe el resumen semanal”, no le importa si el correo sale vía:
- Una herramienta MCP que llama a la API de Resend
- Una skill que ejecuta un comando bash curl
- Un script de TypeScript con credenciales de variables de entorno
- SMTP directo vía sendmail
Lo que les importa es si el correo se envía. Correctamente. Siempre.
Quita las abstracciones y quedan exactamente dos primitivas:
1. Funciones ejecutables — Código que corre y devuelve un resultado (herramientas, herramientas MCP, comandos bash, scripts)
2. Texto de prompt — Instrucciones que la IA lee y sigue (prompts de sistema, skills, archivos CLAUDE.md)
Todo lo demás es empaquetado y estructura organizativa alrededor de estas dos primitivas.
La trampa de la abstracción ocurre cuando optimizas para la taxonomía (elegir entre tipos de herramientas) en lugar de para la confiabilidad (¿esto realmente funciona?).
El principio del ejemplo funcional
Esta es la verdadera unidad de capacidad de un agente de IA:
Un ejemplo funcional con credenciales.
No el registro de una herramienta. No la configuración de un servidor MCP. No una descripción de skill.
Un ejemplo funcional se ve así:
# Enviar correo vía Resend
curl -X POST https://api.resend.com/emails \
-H "Authorization: Bearer $RESEND_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": "[email protected]",
"subject": "Resumen Semanal",
"html": "<p>Contenido aquí</p>"
}'
# Respuesta esperada:
# {"id": "abc-123", "status": "sent"}
# Credenciales: RESEND_API_KEY en .env
# Último test: 2026-02-10
# Responsable: Equipo de MarketingSin un ejemplo funcional, Claude elige arbitrariamente entre 1000 opciones. Con un ejemplo funcional, sigue el patrón probado cada vez.
La diferencia entre “teóricamente puede enviar correos” y “envía correos de manera confiable vía Resend con nuestras credenciales” es un ejemplo funcional probado y documentado.
El modelo de recetas
Una receta es lo que llamamos a un ejemplo funcional probado y comprobado para una tarea específica.
Nuestro Character Director de Marketing tiene estas recetas:
- Enviar correo vía Resend (probado, credenciales en env)
- Consultar la API de Search Console (probado, OAuth configurado)
- Analizar palabras clave vía Ahrefs (probado, API key en env)
- Obtener datos de Google Analytics (probado, ID de propiedad documentado)
Cada receta incluye:
- Cuándo usarla — “Usar para enviar correos transaccionales”
- Referencia de credenciales — “API key: RESEND_API_KEY (en .env)”
- Ejemplo funcional — Comando curl real o fragmento de código que funciona
- Respuesta esperada — Cómo se ve el éxito
- Último test — Fecha en que verificamos que realmente funciona
Las recetas no son definiciones abstractas de herramientas. Son procedimientos concretos y probados que sabemos que funcionan porque los hemos ejecutado.
Las recetas son los bloques de construcción atómicos. Los Characters son composiciones.
Diseño de Characters bottom-up
Esta es la metodología que realmente funciona:
Paso 1: ¿Quién es este Character?
No capacidades abstractas. Rol y propósito específicos.
Mal: “Asistente de IA con capacidades de marketing”
Bien: “Director de Marketing que envía resúmenes de rendimiento semanales a los stakeholders”
Cuanto más claro sea el rol, más fácil será el diseño.
Paso 2: ¿Qué tareas realiza realmente este rol?
No lo que teóricamente podría hacer. Lo que literalmente hace el martes por la mañana.
Para el Director de Marketing:
- Revisar el rendimiento de las campañas (lunes a las 9 am)
- Revisar las tendencias de tráfico orgánico (diariamente)
- Enviar resumen semanal a stakeholders (viernes a las 4 pm)
- Analizar rankings de palabras clave (cuando se solicite)
Nota que estas son tareas, no herramientas. “Revisar el rendimiento de las campañas” es un trabajo a realizar. Si para eso usa la API de Google Ads, Search Console o ambas es un detalle de implementación.
Paso 3: ¿Cómo hacen estas tareas las personas reales?
Aquí es donde te vuelves específico sobre el tech stack.
Para “revisar el rendimiento de las campañas”:
- Una persona real se conecta a Google Analytics
- Ve los últimos 7 días de tráfico
- Compara con el período anterior
- Anota los cambios significativos
Traducción técnica:
- Consultar la API de Google Analytics
- ID de propiedad: 478766521
- Métrica: sesiones, páginas vistas, tasa de rebote
- Rango de fechas: últimos 7 días vs. 7 días anteriores
- Se necesitan credenciales OAuth
Ahora sabes qué receta construir.
Paso 4: ¿Nuestro tech stack lo soporta?
¿Podemos acceder a estas APIs desde nuestro entorno de ejecución?
Verificar:
- ¿Tenemos credenciales? (Revisar .env, revisar configuración OAuth)
- ¿Podemos hacer llamadas a la API desde el sandbox? (Probar comando curl)
- ¿Están instalados los paquetes requeridos? (Revisar imagen Docker o instalar bajo demanda)
Si la respuesta es no:
- Agrega la capacidad a tu entorno de ejecución (instala paquetes, configura OAuth)
- Usa un enfoque diferente (servidor MCP si hay dependencias pesadas)
- Ajusta el rol del Character (reconoce la limitación)
La realidad del entorno de ejecución limita lo posible. Si psql no está instalado en el sandbox, ninguna cantidad de prompt engineering le da a Claude acceso a la base de datos.
Paso 5: Escribe y prueba las recetas
Este es el paso crítico que la mayoría omite.
No escribas:
El agente puede consultar Google Analytics usando la API.Escribe:
# Consultar Google Analytics — Tráfico últimos 7 días
curl -H "Authorization: Bearer $GA_ACCESS_TOKEN" \
"https://analyticsdata.googleapis.com/v1beta/properties/478766521:runReport" \
-d '{
"dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
"metrics": [{"name": "sessions"}]
}'
# Último test: 2026-02-10 (funcionó)
# Responsable: Equipo de Marketing
# Credenciales: GA_ACCESS_TOKEN de OAuth (expira en 1 hora)Luego ejecutarlo de verdad. Verificar que funciona. Corregir lo que falla. Documentar la versión funcional.
La receta sólo es real cuando está probada.
Paso 6: Componer el Character
Ahora tienes:
- Un rol claro (Director de Marketing)
- Tareas específicas (actualizaciones semanales, análisis de tráfico)
- Recetas probadas (Search Console, Analytics, Resend)
El Character es la composición:
# Character: Director de Marketing
## Rol
Eres el Director de Marketing de TeamDay. Monitorizas el rendimiento,
analizas tendencias y comunicas insights a los stakeholders.
## Responsabilidades clave
- Enviar resúmenes de rendimiento semanales (viernes a las 4 pm)
- Monitorizar el tráfico orgánico diariamente
- Analizar rankings de palabras clave bajo demanda
## Recetas disponibles
### Enviar correo vía Resend
Cuándo: Para enviar actualizaciones a stakeholders
Receta: /recipes/send-email-resend.md
### Consultar Search Console
Cuándo: Para analizar tráfico orgánico o palabras clave
Receta: /recipes/search-console-query.md
### Obtener datos de Google Analytics
Cuándo: Para revisar tendencias generales de tráfico
Receta: /recipes/google-analytics-query.md
## Estilo de comunicación
- Directo, sin jerga corporativa
- Comenzar con números ("+15 % de tráfico vs. la semana pasada")
- Explicar qué cambió y por qué importaEl Character referencia las recetas. Las recetas contienen ejemplos funcionales.
Así es como se construyen Characters que realmente funcionan.
Reutilización gracias a la superposición del tech stack
Aquí es donde el modelo de recetas da sus frutos.
El Director de Marketing necesita acceso a Search Console. El Analista SEO necesita acceso a Search Console. La misma receta.
El Representante de Ventas necesita enviar correos. El Director de Marketing necesita enviar correos. La misma receta.
Las recetas se convierten naturalmente en una biblioteca:
/recipes/
├── send-email-resend.md
├── search-console-query.md
├── google-analytics-query.md
├── ahrefs-keyword-analysis.md
├── postgres-query.md
└── notion-page-create.mdCada nuevo Character agrega quizás 1–2 recetas nuevas. La mayoría se reutilizan.
Pero esto sólo funciona si las recetas son ejemplos funcionales probados. Si son definiciones abstractas de herramientas, la reutilización no importa porque de todas formas no funcionan de manera confiable.
El control de calidad
Las capacidades de un Character son tan reales como sus recetas probadas.
Preguntas que hacerse:
No: “¿Este Character tiene el correo configurado?”
Pregunta: “¿Hemos verificado que la receta de correo realmente envía un correo?”
No: “¿Puede este Character acceder a nuestra base de datos?”
Pregunta: “¿Hemos probado la receta de consulta de base de datos con credenciales reales?”
La diferencia entre Characters que son fachadas y Characters que entregan resultados son las recetas probadas.
Aprendimos esto a la mala. Construimos Characters para la página /team de nuestro sitio de marketing. Quedó genial. 14 empleados de IA disponibles para contratar. Descripciones profesionales. Capacidades impresionantes.
Luego intentamos usarlos para trabajo real. La mayoría no funcionó de extremo a extremo. Dependencias faltantes. Recetas sin probar. Capacidades abstractas sin ejemplos funcionales.
El control de calidad: si no lo hemos probado, no lo publicamos.
Realidad del entorno de ejecución: qué es realmente posible
El entorno sandbox limita lo que es posible. Entender estas restricciones lleva a un mejor diseño de Characters.
Lo que funciona en todas partes
APIs HTTP vía curl:
curl -H "Authorization: Bearer $API_KEY" https://api.example.com/endpointCada sandbox tiene curl. Si puedes llegar a una API vía HTTP, puedes integrarla.
Scripts bash:
#!/bin/bash
# Cualquier lógica que puedas scripting funciona en el sandboxHerramientas CLI comunes:
git, grep, sed, awk, jq, node, pythonLo que requiere configuración
Clientes de base de datos:
- Necesitas
psqlomysqlinstalado - Opción 1: Preinstalar en imagen Docker
- Opción 2: Wrapper HTTP API (pg-gateway)
- Opción 3: Servidor MCP para consultas complejas
Paquetes pesados (Puppeteer, Playwright):
- Árboles de dependencias grandes
- Dependencias binarias (Chrome)
- Opción 1: Preinstalar en imagen base (si se usa frecuentemente)
- Opción 2: Servidor MCP (aislado, gestionado por separado)
Flujos OAuth:
- Autenticación interactiva
- Lógica de renovación de tokens
- Opción 1: Preconfigurar tokens (variables de entorno)
- Opción 2: Servidor MCP gestiona la autenticación
Árbol de decisión práctico
- ¿Podemos hacerlo con curl? → Escribe receta, prueba, listo
- ¿Necesitas un paquete < 50 MB? → Instala en imagen Docker
- ¿Necesitas dependencias pesadas? → Servidor MCP (último recurso)
- ¿Necesitas autenticación interactiva? → Servidor MCP o tokens preconfigurados
Cuanto más simples sean los requisitos del entorno de ejecución, más confiable será el Character.
La diferencia con el enfoque habitual
Top-down (enfoque común):
- Elegir framework de agentes de IA
- Configurar servidores MCP
- Agregar skills y herramientas
- Escribir prompt de sistema
- Esperar que funcione
Problemas:
- Herramientas configuradas pero no probadas
- Sin ejemplos funcionales, sólo capacidades abstractas
- El Character teóricamente puede hacer todo, de manera confiable no hace nada
- El primer uso real revela que en realidad no funciona
Bottom-up (nuestro enfoque):
- Definir rol y tareas específicos
- Mapear tareas a flujos de trabajo humanos reales
- Probar y verificar cada flujo de trabajo (escribir recetas)
- Componer Character a partir de recetas probadas
- Control de calidad: cada capacidad está verificada
Resultado:
- Cada receta está probada y se sabe que funciona
- Las capacidades del Character coinciden con la realidad probada
- El primer uso funciona porque las recetas fueron verificadas
- Cuando algo falla, sabemos qué receta corregir
La metodología invierte el proceso: comenzar desde flujos de trabajo verificados, componer hacia arriba hasta los Characters — no configurar herramientas desde arriba y esperar.
Ejemplo real: Director de Marketing
Veamos el proceso de diseño real de uno de nuestros Characters.
Paso 1: Definición del rol
Quién: Director de Marketing de TeamDay Propósito: Monitorizar el rendimiento de marketing y comunicar insights
Paso 2: Tareas reales
Tras observar el trabajo de marketing real:
- Revisar Google Analytics para tendencias de tráfico (diariamente)
- Monitorizar Search Console para rankings de palabras clave orgánicas (semanalmente)
- Enviar resúmenes de rendimiento a stakeholders (semanalmente)
- Analizar campañas específicas cuando se solicite
Paso 3: Flujo de trabajo humano real
Para “enviar resumen semanal”:
- La persona se conecta a Google Analytics
- Ve los últimos 7 días: sesiones, páginas vistas, top páginas
- Compara con la semana anterior
- Anota los cambios significativos
- Revisa Search Console para top consultas
- Redacta correo con los hallazgos
- Envía vía Gmail
Paso 4: Verificación del tech stack
Google Analytics:
- ✅ Tenemos acceso a la API
- ✅ ID de propiedad: 478766521
- ✅ OAuth configurado
- ✅ Podemos consultar vía curl
Search Console:
- ✅ Tenemos acceso a la API
- ✅ Sitio: teamday.ai
- ✅ OAuth configurado
- ✅ Podemos consultar vía curl
Correo electrónico:
- ✅ Usamos Resend (no Gmail)
- ✅ API key en env: RESEND_API_KEY
- ✅ Podemos enviar vía curl
Paso 5: Escribir recetas
Receta 1: Google Analytics — Últimos 7 días
#!/bin/bash
# Obtener tráfico de los últimos 7 días de Google Analytics
curl -H "Authorization: Bearer $GA_ACCESS_TOKEN" \
"https://analyticsdata.googleapis.com/v1beta/properties/478766521:runReport" \
-d '{
"dateRanges": [
{"startDate": "7daysAgo", "endDate": "today"},
{"startDate": "14daysAgo", "endDate": "8daysAgo"}
],
"metrics": [
{"name": "sessions"},
{"name": "totalUsers"},
{"name": "screenPageViews"}
],
"dimensions": [{"name": "pagePath"}]
}'
# Resultado del test (2026-02-10):
# {
# "rows": [
# {"dimensionValues": [{"value": "/"}],
# "metricValues": [{"value": "1243"}, {"value": "892"}, ...]}
# ]
# }
# Credenciales: GA_ACCESS_TOKEN (OAuth, expira en 1 hora)Probado: ✅ Funciona Última verificación: 2026-02-10
Receta 2: Enviar correo vía Resend
#!/bin/bash
# Enviar correo vía API de Resend
TO="$1"
SUBJECT="$2"
BODY="$3"
curl -X POST https://api.resend.com/emails \
-H "Authorization: Bearer $RESEND_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"from\": \"[email protected]\",
\"to\": \"$TO\",
\"subject\": \"$SUBJECT\",
\"html\": \"$BODY\"
}"
# Resultado del test (2026-02-10):
# {"id": "abc-123", "status": "sent"}
# Credenciales: RESEND_API_KEY en .envProbado: ✅ Funciona Última verificación: 2026-02-10
Paso 6: Componer el Character
# Director de Marketing
Eres el Director de Marketing de TeamDay. Monitorizas el rendimiento
y comunicas insights.
## Tarea de resumen semanal
Cada viernes a las 4 pm:
1. Consultar Google Analytics (últimos 7 días vs. anteriores)
Receta: /recipes/google-analytics-7day.sh
2. Consultar Search Console (top consultas orgánicas)
Receta: /recipes/search-console-top-queries.sh
3. Redactar correo:
- Asunto: "TeamDay Marketing Update — Semana del [fecha]"
- Formato:
**Tráfico:** [sesiones] ([+/-]% vs. semana pasada)
**Top páginas:** [listar top 3]
**Top consultas:** [listar top 3]
**Cambios notables:** [todo con >20 % de cambio]
4. Enviar vía Resend
Receta: /recipes/send-email-resend.sh
A: jozo at teamday.aiResultado: Un Character que envía actualizaciones semanales de manera confiable porque cada paso es una receta probada.
Lo que aprendimos a la mala
1. “Probado” significa realmente probado
Documentamos recetas. Se veían bien. Publicamos Characters.
Luego intentamos usarlos. La mitad de las recetas nunca había sido ejecutada. Los endpoints de API habían cambiado. Las credenciales eran incorrectas. Los IDs de propiedad estaban desactualizados.
La solución: Probar cada receta. Ejecutarla de verdad. Verificar la respuesta. Actualizar cuando cambian las APIs.
2. Las recetas se deterioran
Las APIs cambian. Las credenciales expiran. Los servicios se descontinúan.
La solución: Fechar cada receta. Cuando un Character falla, revisar las fechas de las recetas. Volver a probar y actualizar.
3. Las brechas del entorno de ejecución son reales
Diseñamos un Character Analista SQL que consulta nuestra base de datos. Luego descubrimos que psql no estaba instalado en el sandbox.
La solución: Probar las capacidades del entorno de ejecución antes de diseñar Characters. Si psql no está, instalarlo o usar un wrapper HTTP API.
4. La composición supera a la configuración
Pasamos semanas configurando servidores MCP para varias capacidades. Configuración compleja. Muchas piezas en movimiento.
Luego escribimos scripts bash simples con comandos curl. Funcionaron de inmediato.
El aprendizaje: Empezar simple. Los scripts bash con curl te llevan el 80 % del camino. Agrega complejidad sólo cuando lo simple no alcanza.
El insight meta
Toda esta metodología surgió de construir Characters de IA que necesitaban funcionar de verdad — no sólo lucir bien en una demo.
Cuando construyes para demos:
- Las capacidades abstractas están bien
- “Puede enviar correos” es suficiente
- Las capturas de pantalla de configuración lucen impresionantes
Cuando construyes para producción:
- Las recetas probadas son obligatorias
- “Envía correos de manera confiable vía Resend con nuestras credenciales” es el estándar
- Los ejemplos funcionales importan más que la complejidad de la configuración
La diferencia metodológica: las demos optimizan para amplitud de capacidades, la producción optimiza para profundidad de confiabilidad.
Estamos construyendo equipos de IA donde los Characters hacen trabajo real. Eso nos obligó a resolver el problema de la confiabilidad.
La metodología bottom-up centrada en recetas es el resultado.
Pruébalo tú mismo
Para construir un Character que realmente funcione:
-
Define un rol específico No: “IA de Marketing” Sí: “Director de Marketing que envía resúmenes semanales”
-
Lista 3 tareas reales No: “Analizar datos de marketing” Sí: “Revisar el tráfico de los últimos 7 días en Google Analytics”
-
Escribe un ejemplo funcional No documentes herramientas. Escribe un comando curl que funcione. Pruébalo. Verifica la respuesta.
-
Crea un archivo de receta Guarda el ejemplo funcional como
/recipes/nombre-de-tarea.mdIncluye: cuándo usar, credenciales, código funcional, fecha del último test -
Referencia desde el Character El prompt de sistema referencia el archivo de receta El Character sabe cuándo usarlo y cómo invocarlo
-
Prueba end-to-end Usa realmente el Character para la tarea Corrige lo que falla Actualiza la receta
Empieza con una tarea, una receta, un Character.
Una vez que hayas construido uno que funcione de manera confiable, la metodología tiene sentido. Luego escala a más recetas y más Characters.
En nuestra página /team tenemos 14 Characters de IA. Se ven profesionales. Capacidades impresionantes. Pero aprendimos: parecer capaz y ser capaz son cosas distintas.
Los que realmente funcionan tienen recetas probadas. Los que son fachadas tienen definiciones abstractas de herramientas.
La metodología no es complicada: bottom-up desde ejemplos funcionales, componer en Characters, probar end-to-end.
Pero invierte la forma en que la mayoría construye agentes de IA. Y esa inversión es lo que hace que los Characters sean confiables.
Construye desde recetas. Prueba todo. Publica lo que funciona.