AWS Builder Center
Crea tu DJ con IA: tu primer agente en TypeScript, en una hora

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:
  1. Pasamos de Python a TypeScript.
  1. 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.git
cd dj-strands-harness
npm install
Copia el archivo de variables de entorno y llénalo con tus datos:
cp .env.example .env
Dentro 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 login
Las 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 formato  proveedor/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:
  1. Nombre: cómo la llama el modelo.
  1. Descripción: lo que el modelo lee para decidir cuándo usarla.
  1. Schema: las entradas que acepta, descritas con Zod.
  1. 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 es  POST /me/playlists  (antes  /users/{id}/playlists ), agregar canciones es  POST /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.md
Los 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.";
}
});
  •  AfterToolCallEvent  se dispara cada vez que una herramienta corre. Si fue  crear_playlist_en_spotify  y tuvo éxito, anotamos que esa playlist sí existe.
  •  AfterInvocationEvent  revisa la respuesta final del agente. Si promete una playlist y no creamos ninguna en este turno,  event.resume  regresa 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 Bedrock
model: "ollama/llama3.1" // local, gratis
model: "openai/gpt-5.6-sol" // OpenAI
El 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.
  1. La diferencia entre un chatbot y un agente es el loop: razonar, usar una herramienta, volver a razonar. El chatbot habla; el agente hace.
  1. Una herramienta son cuatro cosas: nombre, descripción, schema (Zod) y callback. El modelo lee la descripción y decide cuándo usarla.
  1. 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.
  1. Hay dos memorias: la sesión (la conversación) y la de largo plazo (hechos sobre ti, en markdown que puedes abrir).
  1. Un agente se verifica, no se le cree. Con hooks comparas lo que el agente afirma contra lo que de verdad pasó.
  1. 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.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article