> ## Documentation Index
> Fetch the complete documentation index at: https://phidatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Drive

> GoogleDriveTools let an Agent list, search, read, upload, and download Google Drive files, with smart export of Workspace documents.

`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

<Steps>
  <Step title="Install dependencies">
    ```shell theme={null}
    uv pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib openai
    ```
  </Step>

  <Step title="Setup Google Cloud project">
    Enable the [Google Drive API](https://console.cloud.google.com/apis/enableflow?apiid=drive.googleapis.com), create OAuth credentials, and download the client JSON. First run opens a browser for consent and saves a token for reuse.
  </Step>
</Steps>

## Example

```python cookbook/91_tools/google/drive/basic.py theme={null}
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:

```python theme={null}
GoogleDriveTools(
    corpora="drive",          # "user" | "domain" | "drive" | "allDrives"
    drive_id="0AB...",        # required when corpora="drive"
    supports_all_drives=True,
    include_items_from_all_drives=True,
)
```

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

## 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.

## Developer Resources

* [Tools source](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/google/drive.py)
* [Drive tools example](https://github.com/agno-agi/agno/blob/main/cookbook/91_tools/google/drive/basic.py)
* [File search example](https://github.com/agno-agi/agno/blob/main/cookbook/91_tools/google/drive/file_search.py)
* [Google Drive context provider](/context-providers/providers/drive)