An AI-powered Spotify control agent that provides intelligent music queue management and natural language interaction with your Spotify account.
🎧 You: start auto queue please
🤖 Agent: Auto-queue started! Adding 4 songs every 10 minutes.
🎧 You: queue something by radiohead
🤖 Agent: I'll search for Radiohead and add it to your queue...
🎧 You: what's playing?
🤖 Agent: Currently playing "Everything In Its Right Place" by Radiohead- Pool Management: Fetches 50 songs from your library, uses 20, refreshes every 30 minutes
- Anti-Repetition: Remembers your last 12 tracks to avoid musical déjà vu
- Seamless Experience: Adds 4 songs every 10 minutes for continuous playback
/help- Show available commands/auto-queue- Start intelligent queue monitoring/stop-queue- Stop auto-queue/pool-stats- View song pool statistics/history-songs- Show recent track history/refresh-pool- Force refresh song pool
🗣️ Natural Language Commands — All system commands can also be triggered using natural language:
- Node.js 18+
- Spotify Premium account
- Spotify Developer application
- OpenAI API key
- Spotify MCP Server (repo)
- Clone the required repositories
mkdir spotify-ai && cd spotify-ai
git clone https://github.com/hannasage/spotify-mcp-server.git
git clone https://github.com/hannasage/spotify-agent.git- Setup the Spotify MCP Server
You'll also need to configure an app on the spotify developer dashboard to configure the Spotify MCP server.
cd spotify-mcp-server
cp spotify-config.example.json spotify-config.json
# Edit the contents with the required params- Setup the Spotify Agent
cd ../spotify-agent
npm install
cp .env.example .env- Configure environment variables
# Add to .env file
OPENAI_API_KEY=your_openai_api_key_here
SPOTIFY_MCP_PATH=../spotify-mcp-server/dist/index.js- Run the agent
npm run build
npm start🎵 SPOTIFY AGENT
✅ Multi-agent system ready! Spotify Assistant + Queue Manager + Command Router available.
🎧 You: start auto queue
🎯 Auto-queue monitor started! Will add 4 songs every 10 minutes.
🎵 ANA-LOG AUTO: Added 4 songs to queue
• "Paranoid Android" by Radiohead
• "Karma Police" by Radiohead
• "Creep" by Radiohead
• "No Surprises" by Radiohead- Spotify Assistant: Primary agent handling user interaction and music control with integrated tracing
- Queue Manager: Specialized agent for intelligent music curation and queue management
- Command Router: Routes natural language to appropriate tools and agents with performance monitoring
- MCP Tool Call Interceptor: Real-time monitoring of all Spotify API interactions
- Tool Call Tracer: Comprehensive agent execution tracking and performance analysis
- Song Pool Manager: Intelligent song selection from your library
- Queue Monitor: Autonomous queue management with anti-repetition
- History Tracker: Persistent track history to avoid repetition
- Tool Registry: Modular system for extending functionality
- Performance Evaluation: Real-time trace collection and system analysis
- Tool Call Interceptor: Detailed MCP tool call monitoring and metrics
- OpenAI Agents SDK: Multi-agent orchestration
- Model Context Protocol (MCP): AI-to-API communication
- TypeScript: Type-safe development
- Spotify Web API: Music control and library access
- Evaluation System: Comprehensive performance tracking and analysis
The Spotify Agent includes a comprehensive evaluation system for tracking performance, accuracy, and user experience metrics:
# Run evaluations on collected trace data
npm run eval
# Example evaluation output:
📊 SPOTIFY AGENT EVALUATION REPORT
Session: session_2025_07_19_152437
Grade: A (Score: 92.3/100)
🎯 Performance Metrics:
• Average Response Time: 1.2s
• Tool Call Success Rate: 98.5%
• Agent Execution Time: 850ms
🎵 Accuracy Metrics:
• Command Routing: 94.2%
• Playback Success: 96.8%
• Query Relevance: 89.3%
👤 User Experience:
• Session Duration: 180s
• Interactions: 12
• Conversation Flow: 8.5/10Real-time monitoring captures detailed execution traces:
- MCP Tool Calls: Spotify API interactions with timing and success rates
- Agent Executions: Multi-agent coordination and decision-making
- User Interactions: Input classification and response quality
- System Health: Error rates, connection stability, and performance
- Routing: Input classification accuracy and agent selection
- Tool Calls: MCP server interaction performance and reliability
- Agents: Individual agent execution metrics and success rates
- Interactions: User experience quality and conversation flow
src/
├── agents.ts # Multi-agent configuration
├── queueMonitor.ts # Auto-queue management
├── songPool.ts # Intelligent song selection
├── tools/ # Modular tool system
│ ├── autoQueueTools.ts
│ ├── poolTools.ts
│ ├── historyTools.ts
│ └── systemTools.ts
├── evaluations/ # Performance evaluation system
│ ├── evaluator.ts # Comprehensive metrics analysis
│ ├── schema.ts # Evaluation data structures
│ ├── cli.ts # Evaluation CLI interface
│ └── index.ts # Evaluation system exports
├── lib/ # Enhanced system libraries
│ ├── toolCallTracer.ts # Agent tool call tracing
│ └── mcpToolCallInterceptor.ts # MCP tool call monitoring
├── ui.ts # Rich CLI interface
└── types.ts # TypeScript definitions
npm run build # Build TypeScript
npm run dev # Development mode with auth
npm run debug # Debug mode with verbose logging
npm start # Production mode
npm run clean # Clean build artifacts
npm run eval # Run evaluation system on trace data- Enhanced Debugging: Comprehensive trace collection with MCP tool call interception
- Performance Monitoring: Real-time metrics on agent execution and tool call success rates
- Evaluation Framework: Automated analysis of system performance with graded reports
- Error Tracking: Detailed error capture and recovery analysis
- Create a new tool class extending
BaseTool - Register it in
src/tools/registry.ts - Add appropriate agent instructions
- Tool calls will be automatically traced and included in evaluation reports
We welcome contributions! Please see our Contributing Guidelines for details.
- Enhanced recommendation algorithms
- Additional music service integrations
- Web interface development
- Mobile app development
- Playlist generation features
- Advanced evaluation metrics and analysis
- Machine learning-based performance optimization
- Custom trace collection and visualization tools
ISC License - see LICENSE file for details.
- Built with OpenAI Agents
- Uses Model Context Protocol for AI-to-API communication
- Spotify integration via spotify-mcp-server
Made with ❤️ and modern AI development practices