Agentic Radio DJ

Brief an AI DJ and it programmes a themed radio show — ordered Spotify tracks with short DJ intros — played in your browser via the Web Playback SDK.

I built this as a mini-project to explore Eve and the Vercel AI Gateway — programming a themed radio show from a brief felt like a fun way to learn both in a single app.

Repository: github.com/jacarty/vercel-agentic-dj

The app lives in dj-app/.

• Try without connecting — generate a themed show (tracklist + DJ intros) from a brief with no Spotify login
• Natural-language brief — describe a mood, genre, era, or occasion; the agent streams build progress (briefing, crate-digging, finalising) over NDJSON
• Surprise me — builds a show anchored on a random track from your Liked Songs
• Exclude my library — when enabled, the agent avoids tracks already in your Liked Songs and top tracks so the set feels like discovery
• In-browser playback — Spotify Web Playback SDK with device picker (requires Spotify Premium)
• Save as playlist — export the show as a private Spotify playlist
• Like track — save or remove the now-playing track from Liked Songs
• Show persistence — the last generated show is restored from localStorage on reload
• Build resume — dropped builds re-attach via the Eve session id stored in sessionStorage

• Node.js 24.x
• A Spotify Developer app with redirect URIs registered for dev and production
• Spotify Premium for in-browser playback
• While the Spotify app is in Development mode, only users allowlisted in the dashboard (≤25 accounts) can connect — there is no in-app allowlist

cd dj-app
npm install
cp .env.example .env.local   # fill in your Spotify credentials
npm run dev

Open http://127.0.0.1:3000 — not localhost. PKCE stores the verifier in localStorage, and the app redirects localhost to 127.0.0.1 so the OAuth callback can read it.

Create dj-app/.env.local from the example file:

In production on Vercel, LLM traffic routes through Vercel AI Gateway via OIDC — no separate API key in the repo.

1. Create an app in the Spotify Developer Dashboard.
2. Register redirect URIs (exact match required):
   • Dev: http://127.0.0.1:3000/callback
   • Prod: https://<your-domain>/callback
3. Add required OAuth scopes (requested automatically on login):
   • streaming, user-read-email, user-read-private
   • user-modify-playback-state, user-read-playback-state
   • playlist-modify-private, user-library-read, user-library-modify, user-top-read
4. In User Management, add tester accounts while in Development mode (max 25).

flowchart LR
  Browser -->|PKCE OAuth| Spotify
  Browser -->|POST brief + x-spotify-user-token| ShowAPI["/api/show"]
  ShowAPI -->|WAF dj-build| WAF[Vercel Firewall]
  ShowAPI -->|OIDC| Eve["Eve /eve/v1"]
  Eve --> Tools[search_tracks / finalize_show]
  Tools -->|Client Credentials| Spotify
  Eve -->|Show JSON| Browser
  Browser -->|Web Playback SDK| Spotify

The Eve agent is co-located with the Next.js app via withEve — one same-origin deployment, no separate agent host or CORS configuration.

Agent workflow: plan the energy arc → resolve tracks via search_tracks → write DJ patter → emit the show with finalize_show. Skills (build_energy_arc, write_dj_patter) and tools live under dj-app/agent/.

Deploy to Vercel with the root directory set to dj-app.

• Eve routes are served at /eve/v1/* on the same host as the player
• Configure Vercel Firewall rate-limit rules:
  • dj-build — keyed on Spotify user id (connected users)
  • dj-build-guest — keyed on client IP (guest builds without Spotify)
• Set an AI Gateway usage budget in the Vercel dashboard (recommended cost backstop)
• Register the production Spotify redirect URI before going live

WAF rate limits do not run locally unless you configure firewallHostForDevelopment — see @vercel/firewall docs.

From dj-app/:

Validate with npm run lint and npm run build before deploying. Agent evals live under evals/ — see Evals below.

Eve evals score generated shows: schema validity, track count, version-leak detection, artist diversity, Spotify URI resolution, and (soft) LLM-as-judge theme-fit and intro quality. Run locally — no CI workflow is required.

Requirements: AI Gateway credentials (agent + judge models) and SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET in .env.local. User-token evals (exclude-known, surprise-exclude) need EVAL_SPOTIFY_REFRESH_TOKEN (copy refreshToken from browser localStorage after login) or EVAL_SPOTIFY_USER_TOKEN. Spotify may rotate refresh tokens on each exchange; the runner caches the latest in .eval-spotify-token.json (gitignored). Set EVAL_REQUIRE_SPOTIFY=1 to fail closed when Spotify URI checks cannot run.

cd dj-app
npm run test                # unit tests (classifier, exclusion helpers — free)
npm run eval:smoke          # one build (~60s) — good before a PR
npm run eval refusal seed   # cheap refusal + fixed-seed build (no user token)
npm run eval exclude-known  # fresh brief + library exclusion
npm run eval surprise-exclude  # surprise-me seed + library exclusion
npm run eval                # full suite (17 evals)
npm run eval:ci             # full suite + --strict judges + JUnit (optional)

If eve eval does not auto-boot the dev server, run npm run dev in another terminal and use eve eval --url http://127.0.0.1:3000. Artifacts land in .eve/evals/<timestamp>/. Quality rows use soft LLM judges (theme ≥ 0.7, intros ≥ 0.6) — tracked by default, gated only under --strict.

MIT