Skip to main content
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 instead.

​
Drive vs. Databases

Scout provides multiple storage options. Here’s how Drive compares:
FeatureDriveDatabases & Tables
PurposeFile storage — PDFs, images, documentsStructured data with vector search
Access patternBy path or filenameSemantic, keyword, or hybrid search
Best forAssets, attachments, generated outputsRAG pipelines, knowledge bases, tables
Agent interactionAgents read and write files directlyAgents search by meaning
SyncManual upload or agent writesNotion, Sheets, web scraping
SearchBrowse by folder pathFull-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

1

Upload your first file

Use the API, Python SDK, or TypeScript SDK to upload a file to Drive.
curl -X POST https://api.scoutos.com/drive/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@report.pdf"
When no destination is specified, the file is stored at the root (/) using its original filename.
2

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.
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']}")
3

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.

​
Organizing Files

​
Folder Structure

Design folder hierarchies that match your workflows. Some common patterns: 
/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:
OptionExampleResult
path/docs/report.pdfExact path — highest priority
folder + namefolder=/docs, name=report.pdf/docs/report.pdf
folder onlyfolder=/docs/docs/{original_filename}
name onlyname=report.pdf/report.pdf (stored at root)
Neither—/{original_filename} (stored at root)
Use path whenever you need a deterministic, collision-safe output location. It gives you full control with a single parameter.

​
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

"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

"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

"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: 
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: 
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

Document Processing Pipeline

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.

Automated Reporting

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.

Research and Synthesis

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.

Client Deliverable Management

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.

Agent Handoff

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.

Agent Memory

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.

​
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 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

Drive API Reference

Full endpoint documentation for upload, download, list, create folder, and delete.

Databases Overview

Use Databases when agents need semantic search over structured content.