Spotify Tools
Explore Spotify catalog search and the playlist recipe for eligible Extended Quota Mode apps.
Development Mode apps cannot run this playlist recipe with the current toolkit. Follow the supported-example guidance below before running it.
"""
Example: Using SpotifyTools with an Agno Agent
This example shows how to create an agent that can:
- Search for songs by mood, artist, or genre
- Create playlists based on user requests
- Update existing playlists
"""
from os import getenv
from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools.spotify import SpotifyTools
# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------
# Your Spotify access token (get one from https://developer.spotify.com)
SPOTIFY_TOKEN = getenv("SPOTIFY_TOKEN")
# Initialize the Spotify toolkit
spotify = SpotifyTools(
access_token=SPOTIFY_TOKEN,
default_market="US",
)
# Create an agent with the Spotify toolkit
agent = Agent(
name="Spotify DJ",
model=Claude(id="claude-sonnet-4-20250514"),
tools=[spotify],
instructions=[
"You are a helpful music assistant that can search for songs and manage Spotify playlists.",
"When asked to create a playlist:",
"1. First search for relevant tracks based on the user's criteria (mood, artist, genre)",
"2. Collect the track URIs from the search results",
"3. Create the playlist with those tracks",
"When updating a playlist, use the playlist ID from a previous creation or ask the user for it.",
"Always confirm what you've done and provide the playlist URL when created.",
],
markdown=True,
)
# Example usage
# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
# Example 1: Create a playlist with happy songs from specific artists
response = agent.run(
"Create a Good Vibes playlist, add 5 upbeat songs by The Weeknd and Coldplay in it."
)
print(response.content)
print("\n" + "=" * 50 + "\n")
# Example 2: Update the playlist
# Note: You'd need the playlist_id from the previous response
# response = agent.run(
# "Add 5 more upbeat songs by the Beatles to the Good Vibes playlist"
# )
# print(response.content)Choose the supported example
The playlist recipe above uses legacy Spotify endpoints. It is applicable to eligible Extended Quota Mode apps. Spotify removed those playlist paths for Development Mode apps in its February 2026 migration, and the current Agno toolkit still calls them. Development Mode apps should use the catalog-search example instead; keep search requests at ten results or fewer and ensure the app owner has Spotify Premium.
For the playlist recipe, replace the model with a currently supported Claude model. The script creates a real playlist; it defaults to private, so the token needs playlist-modify-private. It does not refresh expired tokens. Check tracks_added and the playlist itself before claiming every requested track was added: playlist creation can succeed while track insertion fails.
Run the Example
Set up your virtual environment
uv venv --python 3.12
source .venv/bin/activateInstall dependencies
uv pip install -U agno anthropicExport environment variables
export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
export SPOTIFY_TOKEN="your_spotify_token_here"Create a Spotify access token
Create a Spotify OAuth user access token with user-read-private and the playlist scopes required by your playlist visibility: playlist-modify-public and/or playlist-modify-private. See Spotify authorization scopes.
Run the example
Save the code above as spotify_tools.py, then run:
python spotify_tools.pyFull source: cookbook/91_tools/spotify_tools.py