
Crea tu DJ con IA: tu primer agente en TypeScript, en una hora
Un chatbot responde. Un agente hace cosas. Construye un DJ que busca música, arma playlists reales en tu Spotify y recuerda tus gustos, con Strands Harness, TypeScript y Amazon Nova Pro.
Hay un momento, cuando empiezas con agentes de IA, en el que todo parece magia. Le pides algo al modelo y "hace cosas". Pero cuando intentas construir uno de verdad, te das cuenta de que lo difícil no es el modelo: es todo lo que va alrededor. El loop que lo hace razonar, las herramientas que puede usar, la memoria para que no empiece de cero cada vez, el manejo del contexto para que no se dispare el costo.
Hace un tiempo escribí un workshop para construir ese agente capa por capa con el SDK de Strands: armabas el modelo, el loop, la memoria de sesión, todo a mano. Era un gran ejercicio para entender qué hay adentro. Pero en el día a día no quieres armar el motor cada vez que quieres manejar.
Este artículo es la versión nueva de ese workshop, con dos cambios grandes:
- Pasamos de Python a TypeScript.
- Pasamos del SDK a Strands Harness, un agente open source (Apache 2.0) que ya trae el loop, las herramientas, el manejo de contexto, las sesiones y la memoria listos. Tú solo le dices qué es distinto en tu agente.
El ejemplo sigue siendo el mismo, porque es divertido y porque toca una API real: un DJ personal. Un agente que busca canciones, crea playlists en tu cuenta de Spotify, reproduce música en tu dispositivo y recuerda tus gustos entre conversaciones.
Al final vas a tener tu DJ corriendo en tu laptop, conectado a tu Spotify, y el modelo mental de un agente que puedes aplicar a cualquier otra cosa: un asistente de soporte, un agente que revisa tus PRs, uno que organiza tus tickets. Cambian las herramientas, el patrón es el mismo.
Lo que vamos a construir
Vamos a construirlo por capas. Cada capa agrega una capacidad nueva, y puedes parar en cualquier punto y ya habrás aprendido algo funcional.
Capa | Qué aprendes | Conceptos clave |
|---|---|---|
1 - Agente básico | Un modelo que solo habla | createHarness() |
2 - Herramientas | El agente busca y actúa | tool() , Zod, tool calling |
3 - Spotify | Conexión a una API real externa | Spotify Web API |
4 - Memoria | El agente recuerda entre sesiones | sesión vs. memoria de largo plazo |
5 - La guardia | Verificar lo que el agente dice que hizo | hooks del SDK |
El agente corre local, en tu laptop, en Node con TypeScript. El modelo corre en la nube: Amazon Nova Pro en Amazon Bedrock.
De un chatbot a un agente
Antes de escribir código, la idea que lo sostiene todo.
Un chatbot responde con lo que "sabe" de su entrenamiento. Le preguntas por tu biblioteca de música y no la conoce. Le preguntas por algo posterior a su fecha de corte y lo inventa.
Un agente puede usar herramientas. Tú defines funciones (buscar en Spotify, crear una playlist, reproducir una canción) y el modelo decide cuándo llamarlas. Esa decisión la toma solo: mira lo que tiene, elige la herramienta, la usa, recibe el resultado y vuelve a razonar hasta terminar. Eso es el agent loop, y es la línea que separa "saber cosas" de "hacer cosas".
El harness es todo lo que le pones al modelo para que trabaje: las herramientas, la conexión a servicios, la memoria, el manejo del contexto. Imagina que contratas a la persona más brillante que conoces y la sientas en un cuarto vacío, sin computadora, sin internet, sin libreta. Sabe muchísimo, pero no puede hacer nada más que hablar. Ese cuarto es el modelo. El harness es los muebles: lo que le metes para que deje de solo hablar y empiece a trabajar.
Con el SDK amueblabas el cuarto a mano, pieza por pieza. Con el harness viene amueblado en una línea, y aun así puedes mover cada mueble cuando lo necesites.
Prerrequisitos
Antes de empezar, necesitas lo siguiente en tu máquina.
Herramienta | Para qué | Verificar |
|---|---|---|
Node.js 22+ | correr el agente | node --version |
Git | clonar el repo | git --version |
AWS CLI | credenciales para Bedrock | aws --version |
Y dos cuentas:
- Cuenta de AWS con acceso a Amazon Nova Pro en Amazon Bedrock, región
us-east-1. Asegúrate de tener habilitado el acceso al modelo en la consola de Bedrock.
- (Opcional) Cuenta de Spotify con una app creada en developer.spotify.com/dashboard . Reproducir canciones requiere Spotify Premium y la app de Spotify abierta en algún dispositivo. Sin Spotify, el DJ usa una biblioteca local de ejemplo, así que puedes seguir el workshop completo sin cuenta.
Nota: si no tienes acceso a Bedrock, puedes cambiar el modelo a Ollama local y correr todo gratis. Te muestro cómo al final; es literalmente una línea.
Paso 0: Preparar el entorno
Clona el repo e instala las dependencias:
git clone https://github.com/hsaenzG/dj-strands-harness.gitcd dj-strands-harnessnpm installCopia el archivo de variables de entorno y llénalo con tus datos:
cp .env.example .envDentro de
.env van tu AWS_PROFILE (el perfil con acceso a Nova Pro) y, si vas a usar Spotify, tu SPOTIFY_CLIENT_ID y SPOTIFY_CLIENT_SECRET .Consigue credenciales de AWS para Bedrock:
aws loginLas dependencias que instalaste son pocas, y esa es parte de la gracia:
-
@strands-agents/harness: el agente que ya viene armado.
-
@strands-agents/sdk: el SDK por debajo (lo usamos para las herramientas y los hooks).
-
zod: para describir las entradas de cada herramienta.
-
astro: para la interfaz web (opcional).
Capa 1: El agente que solo habla
La primera capa es la más simple: un modelo con instrucciones, sin herramientas. Solo puede responder con lo que sabe.
Con el SDK, esta capa te hacía armar el modelo, el proveedor y el prompt a mano. Con el harness es una sola llamada:
import { createHarness } from "@strands-agents/harness";
const dj = await createHarness({ model: "bedrock/us.amazon.nova-pro-v1:0", instructions: "Eres un DJ personal y curador musical. Respondes en español, con onda y buen gusto musical.",});
await dj("Hola, ¿qué música me recomiendas para programar?");Eso es todo.
createHarness() te devuelve un agente con el loop, el manejo de contexto y las sesiones ya puestos. Le pasas dos cosas:-
model: el modelo, en formatoproveedor/id. Aquí, Nova Pro en Bedrock.
-
instructions: el texto que le da su personalidad y sus reglas.
Córrelo con
npm start y háblale. Cambia las instructions y vas a ver cómo cambia el DJ: pídele que sea sarcástico, o que solo hable de rock de los 90, y la personalidad cambia sin tocar nada más.Pero hay un límite. Pregúntale "¿qué canciones de jazz tengo en mi biblioteca?" y no puede responder. No tiene herramientas. Solo habla. Y aquí es donde se pone interesante.
Capa 2: El agente que busca (herramientas)
El concepto más importante de todo el workshop: tool calling.
Un modelo por sí solo no puede ejecutar código. Pero si le dices "tienes esta herramienta disponible", el modelo decide cuándo invocarla. Tú defines la función, el modelo decide cuándo usarla.
Una herramienta en Strands tiene cuatro partes:
- Nombre: cómo la llama el modelo.
- Descripción: lo que el modelo lee para decidir cuándo usarla.
- Schema: las entradas que acepta, descritas con Zod.
- Callback: la función que corre de verdad.
Así se ve la herramienta para buscar en Spotify, tal cual corre en el repo (recortada para que quepa):
import { tool } from "@strands-agents/sdk";import { z } from "zod";
const buscarEnSpotify = tool({ name: "buscar_en_spotify", description: "Busca canciones en Spotify. Úsala SIEMPRE que el usuario pregunte por música.", inputSchema: z.object({ query: z.string().describe("Texto de búsqueda, admite filtros genre:/artist:"), limite: z.number().default(10).describe("Máximo de resultados, de 1 a 10"), }), callback: async (input) => { const tracks = await sp.searchTracks(input.query, input.limite); return JSON.stringify( tracks.map((t) => ({ titulo: t.name, artista: t.artists[0].name, uri: t.uri })), ); },});Fíjate en el
description y en los .describe() del schema: eso es lo que el modelo lee. No le dices "primero busca, luego responde". Él lee que existe buscar_en_spotify , entiende qué hace, y decide usarla cuando le pides música.Apagamos lo que un DJ no necesita
El harness trae herramientas de propósito general de fábrica: una terminal, herramientas para leer y editar archivos, acceso a la web. Útiles para un agente que trabaja sobre tu máquina, pero un DJ no necesita abrir un shell ni editar archivos. Así que las apagamos y nos quedamos solo con las nuestras:
const dj = await createHarness({ model: "bedrock/us.amazon.nova-pro-v1:0", instructions: INSTRUCCIONES, tools: [...spotifyTools(sp), buscarCanciones], builtinTools: [], // un DJ no necesita shell ni editar archivos builtinPlugins: [], skills: false,});Esto es lo importante del harness: no es una caja negra. Viene todo puesto, y aun así cada default lo cambias con un argumento. Aquí acotamos las herramientas; mañana cambias el modelo, el manejo del contexto o las instrucciones. Empiezas con todo listo y bajas a mano solo lo que necesites.
Cuando le dices "quiero escuchar jazz mientras trabajo", el modelo razona que debe buscar, invoca
buscar_en_spotify(query: "jazz") , recibe la lista y responde con recomendaciones basadas en datos reales. Ya no inventa. Y en la consola vas a ver un chip que dice que usó la herramienta: el modelo lo decidió solo. Eso es el agent loop en acción.Capa 3: Conexión con Spotify (una API real)
Hasta aquí el agente busca, pero todavía no hace. En esta capa damos el salto: el DJ se conecta a la API de Spotify para crear playlists en tu cuenta y reproducir música en tu dispositivo.
El patrón es el mismo de la capa 2: más herramientas con
tool() . El repo trae varias (buscar, reproducir, crear playlist, ver tus top artistas y canciones), y el harness no las trata distinto; se las pasas tal cual en tools .El agente pasó de saber cosas a hacer cosas. Ya no solo recomienda: busca en un catálogo de millones de canciones, crea una playlist real en tu cuenta y la reproduce en tu dispositivo activo. Todo con el mismo patrón: tú defines la herramienta, el modelo decide cuándo y en qué orden usarla.
Nota sobre Spotify en 2026: Spotify cambió su Web API en febrero de 2026. Crear una playlist ahora esPOST /me/playlists(antes/users/{id}/playlists), agregar canciones esPOST /playlists/{id}/items, y la búsqueda devuelve máximo 10 resultados por llamada. El repo ya está migrado a estos endpoints, así que no te vas a pelear con eso.
Si no configuraste Spotify, el DJ usa una biblioteca local (
data/canciones.json ) con una herramienta de plan B que funciona igual de bien para aprender:export const buscarCanciones = tool({ name: "buscar_canciones", description: "Busca canciones en la biblioteca musical LOCAL del usuario por género, mood o artista.", inputSchema: z.object({ genero: z.string().optional().describe("Género musical"), mood: z.string().optional().describe("Estado de ánimo"), artista: z.string().optional().describe("Nombre del artista"), }), callback: ({ genero, mood, artista }) => { const resultados = BIBLIOTECA.filter( (c) => (!genero || norm(c.genero).includes(norm(genero))) && (!mood || norm(c.mood).includes(norm(mood))) && (!artista || norm(c.artista).includes(norm(artista))), ); return JSON.stringify(resultados.slice(0, 10), null, 2); },});Capa 4: El agente que recuerda (dos memorias)
Hasta ahora, cada vez que cierras el programa, el agente empieza de cero. No recuerda que te gusta el rock. No recuerda la playlist del viernes pasado.
Aquí está una de las ventajas grandes del harness sobre armar el agente a mano: trae dos tipos de memoria listos, y los prendes con dos líneas.
const dj = await createHarness({ model: "bedrock/us.amazon.nova-pro-v1:0", instructions: INSTRUCCIONES, session: { id: "nerdearla-mx", dir: SESIONES_DIR }, // corto plazo memory: { dir: MEMORIA_DIR }, // largo plazo});Son dos cosas distintas:
| Sesión (corto plazo) | Memoria (largo plazo) |
|---|---|---|
Qué guarda | La conversación completa | Hechos sobre ti: géneros, artistas, moods |
Dónde | .agent/sessions/<id>/ | .agent/memory/*.md (markdown plano) |
Cuándo | Después de cada mensaje | En segundo plano, cada pocos turnos |
Cómo vuelve | Mismo id = sigue la plática | Se inyecta antes de cada turno |
La sesión guarda el hilo de la conversación. Mismo
id mañana, y el agente retoma donde quedaron.La memoria de largo plazo guarda hechos sobre ti y sobrevive aunque cambies de sesión. Abres una sesión nueva, le preguntas "¿qué recuerdas de mí?", y el DJ igual sabe que te gusta el rock en español y que odias el reggaetón.
Y no es magia. La memoria de largo plazo son archivos de texto en una carpeta de tu proyecto:
.agent/memory/├── user-music-likes.md└── user-dislikes.mdLos abres, los lees, y si quieres los mueves a una base de datos. Nada secreto.
Un detalle honesto: el harness escribe los recuerdos en inglés ("The user dislikes reggaeton.") y los busca por coincidencia de palabras, no por significado. Si el modelo busca "gustos musicales" en español, no encuentra nada. Por eso las instrucciones del DJ le piden buscar en su memoria con palabras en inglés. Es el tipo de detalle que solo descubres construyendo, y vale la pena saberlo de antemano.
Capa 5: Cuando el agente miente (y cómo verificarlo)
Esta es la parte que casi nadie enseña, y la que más me gusta.
Nova Pro a veces narra una acción en vez de ejecutarla. Busca 30 canciones, responde "¡Listo, creé tu playlist!" con un link que suena real, y nunca llamó a
crear_playlist_en_spotify . El link es inventado. La playlist no existe.Puedes pedírselo en las instrucciones ("nunca digas que hiciste algo si no llamaste la herramienta"), y ayuda, pero no basta. Un agente no se verifica con buenas intenciones en el prompt. Se verifica en código.
Como
createHarness() devuelve un Agent normal del SDK, le podemos conectar hooks: funciones que corren en momentos clave del loop. Usamos dos:import { AfterInvocationEvent, AfterToolCallEvent } from "@strands-agents/sdk";
// 1. Anota las playlists que SÍ se crearon.agente.addHook(AfterToolCallEvent, (event) => { if (creoPlaylist(event)) anota(event.result);});
// 2. Revisa la respuesta final. Si promete una que no existe, vuelve al loop.agente.addHook(AfterInvocationEvent, (event) => { if (prometePlaylist(respuesta) && !creadas.size) { event.resume = "No la creaste. Créala de verdad ahora con las URIs reales."; }});-
AfterToolCallEventse dispara cada vez que una herramienta corre. Si fuecrear_playlist_en_spotifyy tuvo éxito, anotamos que esa playlist sí existe.
-
AfterInvocationEventrevisa la respuesta final del agente. Si promete una playlist y no creamos ninguna en este turno,event.resumeregresa al agente a su loop (en la misma invocación) con la orden de crearla de verdad. Máximo una corrección por turno, para no entrar en bucle.
En la práctica, el usuario ve un "🛡️ Verificando…" y el texto falso se reemplaza por el link real que devolvió la herramienta.
Esta es la lección que sirve para cualquier agente que construyas después, no solo para música: un agente se verifica, no se le cree. Separa lo que el agente dice que hizo de lo que de verdad hizo, y verifica la diferencia en código.
Cambiar de modelo es una línea
Terminamos con una de las ventajas de usar un SDK que abstrae el proveedor. ¿No tienes acceso a Bedrock? ¿Quieres correr todo gratis y local? Cambias una línea:
model: "bedrock/us.amazon.nova-pro-v1:0" // Nova en Bedrockmodel: "ollama/llama3.1" // local, gratismodel: "openai/gpt-5.6-sol" // OpenAIEl resto del código (las herramientas, el loop, los hooks, las instrucciones) no cambia. Esa es la gracia: el agente no está casado con un proveedor.
Lo que quiero que te lleves
Si llegaste hasta aquí, construiste un agente de IA funcional desde cero. No es un ejemplo de juguete: busca, recuerda, se conecta a una API real y se verifica a sí mismo.
- La diferencia entre un chatbot y un agente es el loop: razonar, usar una herramienta, volver a razonar. El chatbot habla; el agente hace.
- Una herramienta son cuatro cosas: nombre, descripción, schema (Zod) y callback. El modelo lee la descripción y decide cuándo usarla.
- El harness viene armado pero no es una caja negra.
createHarness()trae el loop, el contexto, las sesiones y la memoria en una línea, y cada default lo cambias con un argumento.
- Hay dos memorias: la sesión (la conversación) y la de largo plazo (hechos sobre ti, en markdown que puedes abrir).
- Un agente se verifica, no se le cree. Con hooks comparas lo que el agente afirma contra lo que de verdad pasó.
- Cambiar de modelo es una línea. Bedrock, Ollama, OpenAI; el resto del código no se entera.
Qué sigue
Ahora la pregunta es: ¿qué vas a construir con esto? El DJ fue la excusa divertida, pero el patrón es el mismo para un agente que consulta tu calendario, uno que revisa tus PRs, uno que organiza tickets de soporte. Cambian las herramientas, cambia el prompt, y el truco de la verificación con hooks aplica igual.
Clona el repo, rómpelo, cámbiale las herramientas y hazlo tuyo. Todo el código (la terminal, la app web en Astro, la guardia y las dos memorias) está en github.com/hsaenzG/dj-strands-harness .
Recursos
¿Te resultó útil este artículo? Si construiste tu propio DJ con variaciones (otras herramientas, otro modelo, otra API), me encantaría ver qué hiciste. Y si algo se te rompió en el camino, cuéntame en los comentarios qué parte te costó más.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article