Daita Logo

Google Drive Plugin

Read, search, and manage Google Drive files with automatic format detection. Built on the Google Drive API v3.

#Installation

bash
pip install 'daita-agents[google]'

#Quick Start

python
from daita import Agent
from daita.plugins import google_drive
 
# Service account (recommended for production)
drive = google_drive(service_account_file="path/to/service_account.json")
 
# Agent uses Google Drive tools autonomously
agent = Agent(
    name="Drive Agent",
    prompt="You are a file management assistant. Help users read and organize their Google Drive files.",
    tools=[drive]
)
 
await agent.start()
result = await agent.run("Find all spreadsheets modified this week and summarize their contents")

#Direct Usage

The plugin can be used directly without agents for programmatic access. For comprehensive Google Drive documentation, see the official Drive API docs. The main value of this plugin is agent integration — enabling LLMs to autonomously read, search, upload, and organize Drive files.

#Connection Parameters

python
google_drive(
    credentials_file: Optional[str] = None,
    service_account_file: Optional[str] = None,
    scopes: Optional[List[str]] = None,
    **kwargs
)

#Parameters

  • credentials_file (str): Path to OAuth 2.0 credentials.json for user authentication (optional)
  • service_account_file (str): Path to a service account key JSON file for server-to-server auth (optional)
  • scopes (list): OAuth scopes to request. Default: ["https://www.googleapis.com/auth/drive"]

If neither file is provided, the plugin falls back to Application Default Credentials (ADC), which supports gcloud auth application-default login and workload identity on GCP.

#Authentication

#Service Account (Recommended for Production)

Best for automated pipelines, Lambda functions, and server-side agents.

python
from daita.plugins import google_drive
 
drive = google_drive(service_account_file="/secrets/service_account.json")
async with drive:
    files = await drive.search("budget report")

Setup:

  1. Create a service account in Google Cloud Console → IAM & Admin → Service Accounts
  2. Download the JSON key file
  3. Share Drive folders/files with the service account email (name@project.iam.gserviceaccount.com)

#OAuth 2.0 (For User-Delegated Access)

Best for accessing a user's personal Drive interactively.

python
drive = google_drive(credentials_file="credentials.json")
# On first run, a browser window opens for OAuth consent.
# Token is cached locally for subsequent runs.
async with drive:
    files = await drive.search("report")

Setup:

  1. Create OAuth 2.0 credentials in Google Cloud Console → APIs & Services → Credentials
  2. Download credentials.json
  3. Enable the Google Drive API in your project

#Application Default Credentials

python
# Uses gcloud auth or GCP workload identity automatically
drive = google_drive()
async with drive:
    files = await drive.list_folder("root")

#Searching Files

python
async with google_drive(service_account_file="sa.json") as drive:
    # Full-text search
    results = await drive.search("quarterly report")
 
    # With MIME type filter
    sheets = await drive.search("budget", mime_type="application/vnd.google-apps.spreadsheet")
 
    # Narrow to a specific folder
    results = await drive.search("report", folder_id="1ABCdef...")
 
    # Returns list of file metadata dicts
    for f in results:
        print(f["id"], f["name"], f["type"])

#Reading File Content

python
async with google_drive(service_account_file="sa.json") as drive:
    # Auto-detects format and extracts content
    content = await drive.read(file_id="1ABCdef...")
 
    # Google Docs → plain text
    # Google Sheets → list of row dicts (CSV export)
    # XLSX → list of row dicts
    # DOCX → plain text
    # PDF → extracted text
    # Plain text / JSON → raw string
 
    print(content["text"])   # or content["rows"] for tabular data

#Listing Folder Contents

python
async with google_drive(service_account_file="sa.json") as drive:
    # List root
    files = await drive.list_folder("root")
 
    # List specific folder by ID
    files = await drive.list_folder("1ABCdef...")
 
    for f in files:
        print(f["id"], f["name"], f["type"], f["modified"])

#Uploading Files

python
async with google_drive(service_account_file="sa.json") as drive:
    # Upload from local path
    file_info = await drive.upload(
        local_path="/data/report.csv",
        name="Q4 Report",
        parent_id="1Folder...",   # optional: parent folder
        mime_type="text/csv"      # optional: overrides auto-detection
    )
    print(file_info["id"])
 
    # Upload from bytes
    file_info = await drive.upload(
        content=b"col1,col2\n1,2",
        name="data.csv",
        mime_type="text/csv"
    )

#Downloading Files

python
async with google_drive(service_account_file="sa.json") as drive:
    local_path = await drive.download(
        file_id="1ABCdef...",
        local_path="/tmp/file.xlsx"
    )
    print(f"Saved to {local_path}")

#Getting File Metadata

python
async with google_drive(service_account_file="sa.json") as drive:
    info = await drive.get_info(file_id="1ABCdef...")
    # Returns: id, name, type, size, created, modified, owners, webViewLink
    print(info)

#Organizing Files

python
async with google_drive(service_account_file="sa.json") as drive:
    # Move file to a folder
    await drive.organize(file_id="1ABCdef...", parent_id="1FolderXYZ...")
 
    # Rename a file
    await drive.organize(file_id="1ABCdef...", name="New Name.xlsx")
 
    # Move and rename in one call
    await drive.organize(
        file_id="1ABCdef...",
        parent_id="1FolderXYZ...",
        name="Archived Report.xlsx"
    )

#Using with Agents

#Tool-Based Integration (Recommended)

The Google Drive plugin exposes Drive operations as tools that agents can use autonomously:

python
from daita import Agent
from daita.plugins import google_drive
import os
 
drive = google_drive(service_account_file=os.getenv("GOOGLE_SA_FILE"))
 
agent = Agent(
    name="Drive Analyst",
    prompt="""You are a data analyst with access to Google Drive.
Help users find, read, and organize their files.""",
    llm_provider="openai",
    model="gpt-4",
    tools=[drive]
)
 
await agent.start()
 
result = await agent.run("""
Summarize this week's reports:
1. Find all spreadsheets created this week in the 'Reports' folder
2. Read each file and extract key metrics
3. Create a consolidated summary
""")
 
print(result)
await agent.stop()

#Available Tools

The Google Drive plugin exposes these tools to LLM agents:

ToolDescriptionParameters
gdrive_searchSearch files by name or contentquery (required), folder_id (str), mime_type (str), limit (int: 20)
gdrive_readRead and extract file contentfile_id (required), sheet_name (str, for multi-sheet XLSX)
gdrive_listList files in a folderfolder_id (default: "root"), limit (int: 50)
gdrive_infoGet file metadatafile_id (required)
gdrive_downloadDownload file to local pathfile_id (required), local_path (required)
gdrive_uploadUpload a file to Drivelocal_path (required), name (str), parent_id (str), mime_type (str)
gdrive_organizeMove or rename a filefile_id (required), parent_id (str), name (str)

Tool Category: storage Tool Source: plugin

#Supported File Formats

FormatMIME Type / ExtensionExtraction Method
Google Docsapplication/vnd.google-apps.documentExported as plain text
Google Sheetsapplication/vnd.google-apps.spreadsheetExported as CSV → rows
Google Slidesapplication/vnd.google-apps.presentationExported as plain text
XLSX.xlsxParsed with openpyxl → rows
DOCX.docxParsed with python-docx → plain text
PDF.pdfText extraction (best effort)
CSV / JSON / Text.csv, .json, .txtRaw string content

#Error Handling

python
from daita.core.exceptions import AuthenticationError, PluginError, ResourceNotFoundError
 
try:
    async with google_drive(service_account_file="sa.json") as drive:
        content = await drive.read("1ABCdef...")
except AuthenticationError as e:
    print(f"Auth failed: {e} — check your credentials file and scopes")
except ResourceNotFoundError as e:
    print(f"File not found: {e} — verify the file ID and sharing permissions")
except PluginError as e:
    print(f"Drive API error: {e}")
except ImportError:
    print("Install the google extra: pip install 'daita-agents[google]'")

#Best Practices

Authentication:

  • Use service accounts for server-side agents — no browser interaction required
  • Share only the folders your service account needs access to (principle of least privilege)
  • Store credentials files outside your repository and reference them via environment variables
  • For user-delegated access, cache the OAuth token file and protect it like a password

Performance:

  • Prefer search() over list_folder() + filtering in Python for large folders
  • Use folder_id in search() to scope results and reduce API calls
  • All blocking Drive SDK calls run in a thread pool — the event loop is never blocked

Security:

  • Never commit service account JSON files to source control
  • Use Workload Identity Federation on GCP instead of downloaded key files when possible
  • Restrict service account permissions to Drive scope only (drive.readonly if writes are not needed)

#Troubleshooting

IssueSolution
google-genai not installedpip install 'daita-agents[google]'
AuthenticationError on connectVerify credentials file path and that the Drive API is enabled
File returns empty contentCheck that the service account has been shared on the file/folder
ResourceNotFoundErrorConfirm the file ID is correct; file may have been deleted or moved
Google Sheets returns no rowsSheet may be empty; verify with gdrive_info first
OAuth browser does not openEnsure you are running locally and have a default browser configured

#Next Steps