DJ Agent Control Flow
A three-layer control architecture: an LLM normalizes free-form input into a canonical command, an executor dispatches it, and three different backends (Spotify Web API with client credentials, Web API with user OAuth, and AppleScript) carry out the action.
DJ Agent's design separates understanding input from executing it, and routes each kind of action to whichever Spotify control surface can perform it. This page documents that flow; the project overview is DJ Agent. Source: ~/Documents/GitHub/dj-agent/README.md, 2026-05-31
The three layers
- LLM normalizer. Free-form text such as "put on some chill vibes" is converted into one
of roughly 20 structured commands. This layer is optional and only active when a
DEDALUS_API_KEYis set; without it, the user types the structured commands directly. - Command executor. Parses the normalized command and dispatches it to the correct backend.
- Backends. Three distinct control surfaces, chosen by what each can do. Source: ~/Documents/GitHub/dj-agent/README.md, 2026-05-31
Why three backends
Each Spotify capability has a different access requirement, so the agent uses the lightest mechanism that works for each. Source: ~/Documents/GitHub/dj-agent/README.md, 2026-05-31
| Action | Backend | Auth |
|---|---|---|
| Search | Spotify Web API | Client credentials (no user login) |
| Queue | Spotify Web API | User OAuth (Authorization Code, token cached locally) |
| Playback (play, pause, skip, volume) | AppleScript to the desktop app | macOS app session |
Search needs only catalog access, so it uses app-level client credentials. Queueing acts on a specific user's playback queue, so it requires a one-time user OAuth consent whose token is cached for later sessions. Playback control of the running desktop app is driven through AppleScript rather than the Web API, which is why the project is macOS-only. Source: ~/Documents/GitHub/dj-agent/README.md, 2026-05-31
Relationship to Kevin's work
The optional natural-language layer is powered by a Dedalus API key with a configurable model, making DJ Agent a compact consumer-facing instance of the input-normalization-then-dispatch pattern used in larger agent systems. Source: ~/Documents/GitHub/dj-agent/README.md, 2026-05-31
Architecture Position
| Axis | Value |
|---|---|
| Family | Agent runtime and control plane |
| Boundary owned | LLM-to-command-to-executor flow for a DJ/event agent. |
| Read with | Agent Runtime Architecture, Tool Execution Runtime Architecture, Ariadne |
| Use this page when | mapping a product-specific agent control flow |
Timeline
-
2026-07-01 | Architecture category refresh added this page to the Agent runtime and control plane family, linked it to Architecture System Map, and kept it standalone because it owns this boundary: LLM-to-command-to-executor flow for a DJ/event agent. Source: User request, 2026-07-01
-
2026-05-31 | Page created from the DJ Agent repository README. Captured the LLM-normalizer to executor to backend flow and the rationale for splitting search (client credentials), queue (user OAuth), and playback (AppleScript) across three control surfaces. Source: ~/Documents/GitHub/dj-agent/README.md, 2026-05-31