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.

spotify_tools.py
"""
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/activate

Install dependencies

uv pip install -U agno anthropic

Export 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.py

Full source: cookbook/91_tools/spotify_tools.py