Drive Folder Organizer

Browses Drive folders with list_files and uploads or downloads local files with write tools enabled.

Browse folders, upload local files to Drive, and download files to a configured local directory.

folder_organizer.py
"""
Drive Folder Organizer
======================
Lists folder contents and helps organize files by uploading to specific locations.

Combines read tools (list_files, search_files) with write tools (upload_file)
to give the agent a complete view of Drive structure.

Key concepts:
- list_files with folder queries: Browse Drive like a file system
- upload_file: Upload local files to Drive (disabled by default, enabled here)
- Drive query syntax: "'<FOLDER_ID>' in parents" to scope to a folder

Setup:
1. Create OAuth credentials at https://console.cloud.google.com (enable Google Drive API)
2. Export GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_PROJECT_ID env vars
3. pip install openai google-api-python-client google-auth-httplib2 google-auth-oauthlib
4. First run opens browser for OAuth consent, saves token.json for reuse
"""

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.google.drive import GoogleDriveTools

agent = Agent(
    name="Drive Organizer",
    model=OpenAIResponses(id="gpt-5.5"),
    tools=[GoogleDriveTools(upload_file=True, download_file=True)],
    instructions=[
        "Help the user explore and organize their Google Drive.",
        "When listing folders, show structure as an indented tree.",
        "Before uploading, confirm the file path and destination with the user.",
        "Before downloading, confirm the destination path.",
    ],
    markdown=True,
)

# ---------------------------------------------------------------------------
# Run Demo
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    # List top-level folders
    agent.print_response(
        "List all folders in the root of my Google Drive",
        stream=True,
    )

    # Explore a specific folder
    # agent.print_response(
    #     "What files are inside the folder called 'Projects'?",
    #     stream=True,
    # )

    # Upload to Drive
    # agent.print_response(
    #     "Upload /tmp/notes.txt to my Google Drive",
    #     stream=True,
    # )

    # Download from Drive
    # agent.print_response(
    #     "Download the file named 'meeting-notes.docx' to /tmp/",
    #     stream=True,
    # )

Upload and download destinations

The current upload_file tool accepts only file_path; it creates a file in Drive's root and cannot target a folder, move files, or create folders. Remove the destination-folder instruction and use the example for browsing and root uploads.

Set download_dir="/tmp" on GoogleDriveTools for the commented download. The tool chooses the Drive filename inside that directory; the prompt cannot override it. Listing root folders uses "'root' in parents and mimeType = 'application/vnd.google-apps.folder'" and may require following nextPageToken.

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U agno google-api-python-client google-auth google-auth-httplib2 google-auth-oauthlib openai openpyxl python-docx python-pptx

Configure Google OAuth

Enable the Google API used by this example, configure the consent screen, and create a Desktop OAuth client in your Cloud project. Export its GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_PROJECT_ID, or place the downloaded client JSON at credentials.json in the directory where you run Python. Google's Python quickstart shows the Desktop client setup.

The first tool call opens a browser for consent and caches credentials in token.json. Use a separate token_path when switching accounts. Passing an Agno user_id does not switch the authenticated Google account.

Export environment variables

export GOOGLE_CLIENT_ID="your_google_client_id_here"
export GOOGLE_CLIENT_SECRET="your_google_client_secret_here"
export GOOGLE_PROJECT_ID="your_google_project_id_here"
export OPENAI_API_KEY="your_openai_api_key_here"

Run the example

Save the code above as folder_organizer.py, then run:

python folder_organizer.py

Full source: cookbook/91_tools/google/drive/folder_organizer.py