Scout Drive: File Storage for AI Agents and Workflows

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:

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

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"

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'}]}

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);

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

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

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:

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)

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:

Download from the source path.
Upload to the new destination path using metadata.path.
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:

List the destination folder before writing new files.
Use explicit paths for all outputs — avoid implicit root writes.
For relocation requests, copy content to the new path, then confirm
   archive or cleanup behavior with the user.
Always confirm the written file path and name in your final response.
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.

Get Started

Agents

Workflows

Data & Storage

Integrations

Platform

Drive

What Is Scout Drive?

Drive vs. Databases

Getting Started

Organizing Files

Folder Structure

Path Resolution

Moving Files Between Folders

What Agents Can Do with Drive

Reading and Summarizing Files

Writing Reports and Exports

Organizing and Relocating Files

Using Drive for Agent Memory

Giving Agents Drive Access

1. Enable the Drive Tool

2. Add Instruction Context

3. Expected Agent Behavior

Practical Use Cases

Document Processing Pipeline

Automated Reporting

Research and Synthesis

Client Deliverable Management

Agent Handoff

Agent Memory

Troubleshooting

Best Practices

Next Steps

Drive API Reference

Databases Overview

​What Is Scout Drive?

​Drive vs. Databases

​Getting Started

​Organizing Files

​Folder Structure

​Path Resolution

​Moving Files Between Folders

​What Agents Can Do with Drive

​Reading and Summarizing Files

​Writing Reports and Exports

​Organizing and Relocating Files

​Using Drive for Agent Memory

​Giving Agents Drive Access

​1. Enable the Drive Tool

​2. Add Instruction Context

​3. Expected Agent Behavior

​Practical Use Cases

Document Processing Pipeline

Automated Reporting

Research and Synthesis

Client Deliverable Management

Agent Handoff

Agent Memory

​Troubleshooting

​Best Practices

​Next Steps

Drive API Reference

Databases Overview

What Is Scout Drive?

Drive vs. Databases

Getting Started

Organizing Files

Folder Structure

Path Resolution

Moving Files Between Folders

What Agents Can Do with Drive

Reading and Summarizing Files

Writing Reports and Exports

Organizing and Relocating Files

Using Drive for Agent Memory

Giving Agents Drive Access

1. Enable the Drive Tool

2. Add Instruction Context

3. Expected Agent Behavior

Practical Use Cases

Troubleshooting

Best Practices

Next Steps