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

# Scout Drive: File Storage for AI Agents and Workflows

> Scout Drive is built-in file storage for agents and workflows. Upload PDFs and documents, then let agents read, write, and organize files autonomously.

Scout Drive is the file storage layer built directly into your Scout workspace. When your agents need to read a contract, save a generated report, or pass a document between workflow steps, Drive is where those files live. Unlike external storage services, Drive is natively connected to your agents and workflows — no integration setup, no separate credentials, no glue code.

## What Is Scout Drive?

Drive handles file I/O for your entire Scout workspace. It supports any file type your agents produce or consume: PDFs, images, markdown reports, CSVs, Word documents, exported data, and more. You can upload files manually via the API or SDK, and agents can read and write files autonomously as part of their tasks.

Drive is purpose-built for file operations. For structured data that your agents need to search semantically — FAQs, documentation, knowledge bases — use [Databases](/databases/overview) instead.

## Drive vs. Databases

Scout provides multiple storage options. Here's how Drive compares:

| Feature               | Drive                                  | Databases & Tables                     |
| --------------------- | -------------------------------------- | -------------------------------------- |
| **Purpose**           | File storage — PDFs, images, documents | Structured data with vector search     |
| **Access pattern**    | By path or filename                    | Semantic, keyword, or hybrid search    |
| **Best for**          | Assets, attachments, generated outputs | RAG pipelines, knowledge bases, tables |
| **Agent interaction** | Agents read and write files directly   | Agents search by meaning               |
| **Sync**              | Manual upload or agent writes          | Notion, Sheets, web scraping           |
| **Search**            | Browse by folder path                  | Full-text and vector search            |

**Use Drive when you need to:**

* Store PDFs or documents for agents to read and summarize
* Save generated reports, exports, or deliverables
* Pass files between workflow steps
* Manage reference assets like prompt templates or checklists
* Persist agent outputs across sessions

**Use Databases when you need to:**

* Build RAG applications with semantic search
* Store structured data in queryable tables
* Create knowledge bases agents search with natural language
* Sync data from Notion, Google Sheets, or scraped websites

## Getting Started

<Steps>
  <Step title="Upload your first file">
    Use the API, Python SDK, or TypeScript SDK to upload a file to Drive.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.scoutos.com/drive/upload \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -F "files=@report.pdf"
      ```

      ```python Python theme={null}
      from scoutos import Scout

      client = Scout(api_key="YOUR_API_KEY")

      result = client.drive.upload(files=["report.pdf"])

      print(result)
      # {'data': [{'url': 'https://...', 'name': 'report.pdf', 'id': 'file_abc123'}]}
      ```

      ```typescript TypeScript theme={null}
      import { ScoutClient } from "scoutos";
      import * as fs from "fs";

      const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });

      const result = await client.drive.upload({
        files: [fs.createReadStream("report.pdf")]
      });

      console.log(result);
      ```
    </CodeGroup>

    When no destination is specified, the file is stored at the root (`/`) using its original filename.
  </Step>

  <Step title="Organize files into folders">
    Create a folder structure that mirrors how your agents work. Use the `folder` or `path` metadata field to control where each file lands.

    ```python theme={null}
    from scoutos import Scout

    client = Scout(api_key="YOUR_API_KEY")

    # Create the destination folder
    client.drive.create_folder(path="/reports/2026")

    # Upload into that folder
    client.drive.upload(
        files=["q1_summary.pdf"],
        metadata=[{"folder": "/reports/2026", "name": "q1_summary.pdf"}]
    )

    # List the folder contents
    files = client.drive.list(folder="/reports/2026")
    for file in files["data"]["files"]:
        print(f"{file['name']} — {file['path']}")
    ```
  </Step>

  <Step title="Give your agent Drive access">
    Open your agent in Scout, go to the **Tools** tab, and enable **Drive**. Once enabled, your agent can read and write files using natural language instructions.

    Try this prompt:

    > "Read `/reports/2026/q1_summary.pdf` and extract the top three findings."

    Your agent locates the file, reads it, and returns a structured response — no code required.
  </Step>
</Steps>

## Organizing Files

### Folder Structure

Design folder hierarchies that match your workflows. Some common patterns:

```text theme={null}
/inbox          — files waiting to be processed
/reports        — generated outputs, organized by date or type
/exports        — data exports and CSV files
/archive        — older files moved out of active paths
/memory         — agent-persisted notes and goals
/clients        — per-client deliverables and assets
/briefs         — synthesized research and summaries
```

### Path Resolution

When you upload a file, Drive resolves its destination path using the following priority order:

| Option            | Example                           | Result                                  |
| ----------------- | --------------------------------- | --------------------------------------- |
| `path`            | `/docs/report.pdf`                | Exact path — highest priority           |
| `folder` + `name` | folder=`/docs`, name=`report.pdf` | `/docs/report.pdf`                      |
| `folder` only     | folder=`/docs`                    | `/docs/{original_filename}`             |
| `name` only       | name=`report.pdf`                 | `/report.pdf` (stored at root)          |
| Neither           | —                                 | `/{original_filename}` (stored at root) |

<Tip>
  Use `path` whenever you need a deterministic, collision-safe output location. It gives you full control with a single parameter.
</Tip>

### Moving Files Between Folders

Drive doesn't have a dedicated move endpoint. Use this three-step pattern to relocate files:

1. Download from the source path.
2. Upload to the new destination path using `metadata.path`.
3. Archive or delete the source when appropriate.

This keeps relocations explicit and visible in workflow logs.

## What Agents Can Do with Drive

Once Drive is enabled as a tool, agents can perform a wide range of file operations autonomously.

### Reading and Summarizing Files

```text theme={null}
"Read /contracts/incoming/acme_nda.pdf and summarize the key obligations."
"Find all files in /reports/monthly and tell me which ones are missing an executive summary."
"Read the latest file in /exports/crm and identify any contacts without an assigned owner."
```

### Writing Reports and Exports

```text theme={null}
"Write a daily standup summary to /reports/daily/2026-05-04.md."
"Export this contact list to a CSV and save it to /exports/crm/."
"Create a markdown brief from this meeting transcript and save it to /briefs/."
```

### Organizing and Relocating Files

```text theme={null}
"Create /archive/2025/q4, then move all files from /reports/q4-2025 into it."
"List everything in /handoff and tell me which files are older than 30 days."
"Rename /drafts/brief-v1.md to /drafts/brief-final.md."
```

### Using Drive for Agent Memory

Agents can use Drive to persist information across sessions — keeping state visible and inspectable as plain files:

```text theme={null}
User:  "Remember that our Q1 revenue target is $2.4M."
Agent: "Saved to /memory/goals.md. I'll reference this in future conversations."
```

This pattern works well for long-running agents that need to maintain goals, preferences, or context between interactions.

## Giving Agents Drive Access

### 1. Enable the Drive Tool

In your agent's **Tools** tab, enable **Drive**. This grants the agent permission to read and write files within your workspace.

### 2. Add Instruction Context

Include the following in your agent's system prompt to encourage consistent, safe file behavior:

```markdown theme={null}
When handling file tasks:

1. List the destination folder before writing new files.
2. Use explicit paths for all outputs — avoid implicit root writes.
3. For relocation requests, copy content to the new path, then confirm
   archive or cleanup behavior with the user.
4. Always confirm the written file path and name in your final response.
5. Never delete folders unless the user explicitly requests cleanup.
```

### 3. Expected Agent Behavior

With Drive enabled and clear system prompt guidance, your agents will:

* Check folder contents before writing to avoid collisions
* Use predictable, deterministic paths when creating files
* Confirm the output location after each write
* Avoid destructive cleanup unless explicitly asked

## Practical Use Cases

<CardGroup cols={2}>
  <Card title="Document Processing Pipeline" icon="file-lines">
    Upload incoming contracts to `/contracts/incoming`. Your agent reads each file, extracts key clauses, and writes a structured summary to `/contracts/summaries`. A workflow routes summaries to the right team channel.
  </Card>

  <Card title="Automated Reporting" icon="chart-bar">
    An agent runs on a schedule, pulls data from your CRM integration, and writes a formatted markdown report to `/reports/daily/{date}.md`. Stakeholders access the latest report directly from Drive.
  </Card>

  <Card title="Research and Synthesis" icon="microscope">
    An agent reads multiple PDFs in a `/research` folder, synthesizes findings, and writes a consolidated brief to `/briefs/`. It lists what it read so the output is fully auditable.
  </Card>

  <Card title="Client Deliverable Management" icon="briefcase">
    Agents generate proposals, summaries, or exports and save them to client-specific folders like `/clients/acme/deliverables/`. Each output is timestamped and versioned by filename.
  </Card>

  <Card title="Agent Handoff" icon="right-left">
    Multiple agents share a `/handoff` folder. Agent A writes a structured context file after finishing its task. Agent B reads that file at the start of its run to pick up where the first agent left off.
  </Card>

  <Card title="Agent Memory" icon="brain">
    Agents persist goals, preferences, and session notes to `/memory/`. This pattern keeps long-running agent state visible and inspectable rather than buried in opaque context windows.
  </Card>
</CardGroup>

## Troubleshooting

**File not found after upload**

Check the path you specified in the `metadata` parameter. If no `folder` or `path` was set, the file was saved to the root (`/`). Run `client.drive.list(folder="/")` to confirm its location.

**Agent is not finding files**

Verify that Drive is enabled in the agent's **Tools** tab. Also confirm the file path you're referencing exists exactly as specified — paths are case-sensitive.

**Agent writes to the wrong location**

Add explicit path guidance to your system prompt. The instruction snippet in [Giving Agents Drive Access](#giving-agents-drive-access) helps agents default to predictable, scoped paths.

**Upload fails with a 413 or size error**

The file exceeds the size limit for your Scout plan. For large files, consider splitting the content into smaller chunks or compressing the file before upload.

**Folder delete removed files I needed**

Drive folder deletion is permanent. Use the archive pattern — move files to `/archive/...` — instead of deleting when you want to preserve history. Only call `delete_folder` when you are certain the contents are no longer needed.

## Best Practices

* Use descriptive, date-stamped filenames for generated outputs (for example, `standup-2026-05-04.md`).
* Keep folder conventions stable — agents perform better with consistent, predictable paths.
* Separate input and output paths (for example, `/inbox` vs. `/reports`) to avoid accidental overwrites.
* Schedule regular archive jobs to prevent storage sprawl.
* Use Databases instead of Drive when your agents need to search content semantically.

## Next Steps

<CardGroup cols={2}>
  <Card title="Drive API Reference" icon="code" href="/drive/api-reference">
    Full endpoint documentation for upload, download, list, create folder, and delete.
  </Card>

  <Card title="Databases Overview" icon="layer-group" href="/databases/overview">
    Use Databases when agents need semantic search over structured content.
  </Card>
</CardGroup>