# Spotify Tools (/examples/tools/spotify-tools)



<Warning>
  Development Mode apps cannot run this playlist recipe with the current toolkit. Follow the supported-example guidance below before running it.
</Warning>

```python title="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 [#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](https://developer.spotify.com/documentation/web-api/tutorials/february-2026-migration-guide), and the current Agno toolkit still calls them. Development Mode apps should use the [catalog-search example](/tools/toolkits/others/spotify#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](/models/providers/native/anthropic/overview). 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 [#run-the-example]

<Steps>
    <Step title="Set up your virtual environment">
      <CodeBlockTabs defaultValue="Mac">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="Mac">
            Mac
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="Windows">
            Windows
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="Mac">
          ```bash
          uv venv --python 3.12
          source .venv/bin/activate
          ```
        </CodeBlockTab>

        <CodeBlockTab value="Windows">
          ```bash
          uv venv --python 3.12
          .venv\Scripts\activate
          ```
        </CodeBlockTab>
      </CodeBlockTabs>
    </Step>

  <Step title="Install dependencies">
    ```bash
    uv pip install -U agno anthropic
    ```
  </Step>

  <Step title="Export environment variables">
    <CodeBlockTabs defaultValue="Mac/Linux">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="Mac/Linux">
          Mac/Linux
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="Windows">
          Windows
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="Mac/Linux">
        ```bash
        export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
        export SPOTIFY_TOKEN="your_spotify_token_here"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="Windows">
        ```bash
        $Env:ANTHROPIC_API_KEY="your_anthropic_api_key_here"
        $Env:SPOTIFY_TOKEN="your_spotify_token_here"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>

  <Step title="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](https://developer.spotify.com/documentation/web-api/concepts/scopes).
  </Step>

  <Step title="Run the example">
    Save the code above as `spotify_tools.py`, then run:

    ```bash
    python spotify_tools.py
    ```
  </Step>
</Steps>

Full source: [cookbook/91\_tools/spotify\_tools.py](https://github.com/agno-agi/agno/blob/8f36eaf2d18e91afa7b327eec66a3cd3685dcb87/cookbook/91_tools/spotify_tools.py)