Google Drive

GoogleDriveTools give an Agent access to Google Drive. Reading tools (list_files, search_files, read_file) are enabled by default. Writing tools (upload_file, download_file) are off by default and must be opted into. Workspace files (Docs, Sheets, Slides) are auto-exported to text the LLM can consume.

Getting Started

Install dependencies

uv pip install agno google-api-python-client google-auth-httplib2 google-auth-oauthlib openai

Setup Google Cloud project

Enable the Google Drive API, create OAuth credentials, and download the client JSON. First run opens a browser for consent and saves a token for reuse.

Example

cookbook/91_tools/google/drive/basic.py

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

# Read-only agent (default -- upload and download disabled)
read_only_agent = Agent(
    name="Drive Reader",
    model=OpenAIResponses(id="gpt-5.5"),
    tools=[GoogleDriveTools()],
    instructions=[
        "When listing or searching files, show the file ID, name, type, and last modified date.",
        "When reading files, summarize the content briefly.",
        "Google Docs and Slides are exported as plain text, Sheets as CSV.",
    ],
    markdown=True,
)

# Full-access agent with upload and download enabled
full_agent = Agent(
    name="Drive Agent",
    model=OpenAIResponses(id="gpt-5.5"),
    tools=[GoogleDriveTools(upload_file=True, download_file=True)],
    instructions=[
        "When uploading files, confirm the file path with the user first.",
        "When downloading files, ask for the destination path.",
        "Show file metadata in a structured markdown format.",
    ],
    markdown=True,
)

Authentication

Method	How
OAuth	Pass `credentials_path` (client JSON) and `token_path`, or use the defaults `credentials.json` and `token.json`.
Service account	Pass `service_account_path` (or set `GOOGLE_SERVICE_ACCOUNT_FILE`). Use `delegated_user` for domain-wide delegation.
Pre-built creds	Pass a `Credentials` object directly via `creds`.

Scopes are auto-inferred from the enabled tools (read-only by default, write scope added when upload_file=True). Override with scopes.

Shared Drives

Set the Drive API passthrough params to search across Shared Drives:

GoogleDriveTools(
    corpora="drive",          # "user" | "domain" | "drive" | "allDrives"
    drive_id="0AB...",        # required when corpora="drive"
    supports_all_drives=True,
    include_items_from_all_drives=True,
)

Results are capped at 20 per call by default to prevent context overflow. Increase max_results if your model has a larger context window.

Toolkit Params

Parameter	Type	Default	Description
`max_results`	`int`	`20`	Maximum results per API request to prevent context overflow.
`list_files`	`bool`	`True`	Enable the `list_files` tool.
`search_files`	`bool`	`True`	Enable the `search_files` tool.
`read_file`	`bool`	`True`	Enable the `read_file` tool.
`upload_file`	`bool`	`False`	Enable the `upload_file` tool.
`download_file`	`bool`	`False`	Enable the `download_file` tool.
`download_dir`	`Path`	`.`	Save location for `download_file`. Writes are sandboxed here.
`include_trashed`	`bool`	`False`	Include trashed files in search/list results.
`max_read_size`	`int`	`10485760`	Max file size (bytes) `read_file` loads for non-Workspace files.
`scopes`	`Optional[List[str]]`	auto-inferred	OAuth scopes. Inferred from enabled tools when `None`.
`creds`	`Optional[Credentials]`	`None`	Pre-built credentials object. Skips the auth flow.
`credentials_path`	`Optional[str]`	`None`	OAuth client credentials JSON path. Defaults to `credentials.json`.
`token_path`	`Optional[str]`	`None`	OAuth token file path. Defaults to `token.json`.
`oauth_port`	`Optional[int]`	`None`	Port for the OAuth callback. Defaults to `5050`.
`login_hint`	`Optional[str]`	`None`	Email to pre-select in the OAuth consent screen.
`service_account_path`	`Optional[str]`	`None`	Service account JSON path. Alternative to OAuth.
`delegated_user`	`Optional[str]`	`None`	User to impersonate via domain-wide delegation.
`quota_project_id`	`Optional[str]`	`None`	GCP project to bill API usage to. Falls back to `GOOGLE_CLOUD_QUOTA_PROJECT_ID`.
`corpora`	`str`	`"user"`	Shared Drive scope: `user`/`domain`/`drive`/`allDrives`.
`supports_all_drives`	`bool`	`False`	Enable Shared Drive API features.
`include_items_from_all_drives`	`bool`	`False`	Include Shared Drive items in results.
`drive_id`	`Optional[str]`	`None`	Shared Drive ID. Required when `corpora="drive"`.
`instructions`	`Optional[str]`	`None`	Custom instructions. Defaults to built-in Drive query syntax guidance.
`add_instructions`	`bool`	`True`	Inject the instructions into the agent system prompt.

Toolkit Functions

Function	Description
`list_files`	List files, optionally filtered by a Drive query.
`search_files`	Search files by Drive query, returns metadata and links.
`read_file`	Read a file's content. Workspace files are exported to text/CSV.
`upload_file`	Upload a local file to Drive.
`download_file`	Download a file to `download_dir`. Workspace files export to native formats.

All functions have sync and async variants.

Office document extraction

For optional DOCX, XLSX, and PPTX text extraction, install python-docx, openpyxl, and python-pptx respectively. Other binary formats are not arbitrary text parsers; use the download tool or a reader suited to the format.

Shared Google authentication

The current Google Workspace toolkits accept auth=AuthConfig(...) through their shared base class. Reuse one config across Drive, Sheets, Slides, or Calendar toolkits to aggregate the scopes before the first authentication:

from agno.tools.google.auth import AuthConfig

auth = AuthConfig(interactive=False, http_timeout=60)

Pass auth=auth to each toolkit constructor. This headless configuration requires existing usable credentials; it raises instead of opening a browser when interactive authorization would be needed. For an initial local OAuth sign-in, use interactive=True with the client credentials described above.

AuthConfig also accepts a supported db for token storage. Encryption is enabled by default and requires a token_encryption_key (or GOOGLE_TOKEN_ENCRYPTION_KEY). Its database token identity is shared for this Google configuration; it does not automatically select credentials by the agent's user_id. Put service-account and delegated-user settings on AuthConfig when using auth=, rather than mixing those legacy constructor arguments. Service accounts must have the target resources shared with them or appropriate delegated access.

See the AuthConfig source for the full configuration.