Spotify | Agno

SpotifyTools enable an Agent to search Spotify's catalog and access authenticated-user playback data.

Prerequisites

The example requires a Spotify access token from Spotify and an Anthropic API key. It enables only catalog search, so the Spotify token does not need playlist modification scopes.

uv pip install -U agno anthropic

export SPOTIFY_TOKEN=***
export ANTHROPIC_API_KEY=***

Spotify changed several endpoints and response fields for Development Mode apps in February 2026. Extended Quota Mode apps are unaffected. The current Agno adapter still uses the earlier paths and fields, so the affected methods below are unavailable to Development Mode apps. Use the read-only example until SpotifyTools is updated. See Spotify's February 2026 migration guide.

Example

The following agent searches Spotify for tracks and returns their names and URIs.

cookbook/91_tools/spotify_tools.py

from os import getenv

from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools.spotify import SpotifyTools

# 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",
    include_tools=["search_tracks"],
)

# Create an agent with the Spotify toolkit
agent = Agent(
    name="Spotify DJ",
    model=Claude(id="claude-sonnet-5"),
    tools=[spotify],
    instructions=[
        "Search Spotify for tracks that match the request.",
        "Return each track's name, artists, and Spotify URI.",
    ],
    markdown=True,
)

response = agent.run("Find five tracks by The Weeknd.")
print(response.content)

Toolkit Params

Parameter	Type	Default	Description
`access_token`	`str`	-	Spotify OAuth access token with required scopes.
`default_market`	`Optional[str]`	`"US"`	Default market/country code for search results.
`timeout`	`int`	`30`	Request timeout in seconds.

Toolkit Functions

Function	Description
`search_tracks`	Search for tracks on Spotify
`search_playlists`	Unavailable to Development Mode apps in the current Agno adapter because it expects the earlier playlist response fields
`search_artists`	Search for artists on Spotify
`search_albums`	Search for albums on Spotify
`get_user_playlists`	Unavailable to Development Mode apps in the current Agno adapter because it expects the earlier response fields
`get_track_recommendations`	Restricted for new and Development Mode apps by Spotify's November 2024 API changes; requires eligible prior access.
`get_artist_top_tracks`	Unavailable to Development Mode apps because Spotify removed the endpoint
`get_album_tracks`	Get tracks from a specific album
`get_my_top_tracks`	Get current user's top tracks
`get_my_top_artists`	Get current user's top artists
`create_playlist`	Unavailable to Development Mode apps in the current Agno adapter because it calls the removed user-specific endpoint
`add_tracks_to_playlist`	Unavailable to Development Mode apps in the current Agno adapter because it calls the removed `/tracks` endpoint
`get_playlist`	For Development Mode apps, use `include_tracks=False`; item parsing expects the earlier field names
`update_playlist_details`	Update playlist name, description, or other details
`remove_tracks_from_playlist`	Unavailable to Development Mode apps in the current Agno adapter because it calls the removed `/tracks` endpoint
`get_current_user`	Get current user's profile information
`play_track`	Start or resume playback (requires an active Spotify session)
`get_currently_playing`	Get information about currently playing track

Development Mode setup

Development Mode apps require their owner to have Spotify Premium. Keep search requests at 10 results or fewer: the current Development Mode endpoint rejects higher limits even though the Agno method permits up to 50. The example's five-track request fits that limit. Extended Quota Mode apps are unaffected by the February 2026 migration described above.

Developer Resources

Tools