Scout Drive

Store, organize and serve files to your agents and workflows.

What is Scout Drive?

Scout Drive is Scout’s built-in file system. Use it when your AI apps need file I/O, not semantic retrieval.

Drive is great for PDFs, exports, generated reports, images and attachments. Agents can read files, create new files and organize folders as part of normal task execution.

Key Features

• File upload and download: Move files in and out with API and SDK
• Folder management: Create, list and remove folder trees
• Deterministic paths: Control destination with path, folder and name
• Agent tool support: Let agents read and write files directly
• Workflow compatibility: Use Drive files in recurring automations

Drive vs. Databases

Scout offers two storage solutions:

When to Use Drive

Use Drive for:

• Storing PDF documents for agents to read
• Uploading images for processing workflows
• Storing CSV exports or reports
• Managing assets for Copilot integrations

When to Use Databases

Use Databases for:

• Building RAG applications with semantic search
• Storing structured data in tables
• Knowledge bases that need vector search
• Syncing data from Notion, Google Sheets or web sources

Give Agents Drive Access

1) Enable Tools

If you want agents to manage files, enable Drive in the agent’s Tools tab.

Once enabled, agents can:

• Read files and summarize content
• Write outputs like CSVs, markdown reports and exports
• Create folders and organize file destinations
• List folder contents before taking action

Example prompts:

• “Read /reports/q1-summary.pdf and extract topline metrics.”
• “Create /reports/weekly, then save this summary as 2026-02-27.md.”
• “List files in /handoff and tell me which ones are missing metadata.”

2) Add Instruction Snippet

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

3) Prompt Examples

• “Read all files in /contracts/incoming and create summaries in /contracts/summaries.”
• “Create /reports/monthly/2026, then write this report to /reports/monthly/2026/feb.md.”
• “Move files from /handoff to /archive/handoff/2026-02 and list what moved.”

4) Expected Behavior

• The agent checks folder contents before writes
• The agent uses deterministic paths when creating files
• The agent confirms output location after each write
• The agent avoids destructive cleanup unless explicitly requested

Agent Operations Playbook

Use this pattern when building production agents that touch Drive.

1. Plan destination paths: Use predictable folders like /reports/daily or /exports/crm.
2. Check before write: List the target folder to avoid accidental collisions.
3. Write with explicit metadata: Prefer path for deterministic output locations.
4. Read and verify: For critical outputs, read back and validate file content.
5. Archive in batches: Clean old folders on a schedule.

Quick Start

Upload a File

Using the API:

curl -X POST https://api.scoutos.com/drive/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@report.pdf"

Using Python:

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

Using TypeScript:

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

Download a File

Using the API:

curl -X GET "https://api.scoutos.com/drive/download?path=/report.pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output report.pdf

Using Python:

content = client.drive.download(path="/report.pdf")

Using TypeScript:

const content = await client.drive.download({ path: "/report.pdf" });

Organizing Files

Creating and Managing Folders

Folders help you organize files into logical structures. You can create folders for different projects, agents or use cases.

Create a Folder:

from scoutos import Scout
 
client = Scout(api_key="YOUR_API_KEY")
 
# Create a new folder
result = client.drive.create_folder(path="/projects/research")

List Folder Contents:

# List all files in a folder
files = client.drive.list(folder="/projects/research")
 
for file in files:
    print(f"{file['name']} - {file['path']}")

Delete a Folder:

# Delete a folder and all its contents
client.drive.delete_folder(path="/projects/archived")

Moving Files Between Folders

Drive pathing gives you strong control for new writes. For existing files, a common pattern is:

1. Download from the source path
2. Upload to the new destination path
3. Archive or clean up old folders when appropriate

This keeps relocation explicit and auditable in workflow logs.

Folder Structure

Organize your files using folder hierarchies:

# Upload to a specific folder
client.drive.upload(
    files=["q1_report.pdf"],
    metadata=[{"folder": "/reports/2024", "name": "q1_report.pdf"}]
)

Path Resolution

When uploading, you can specify file destinations in several ways:

Agent File Access

Agents can read and write files directly from Drive.

Reading Files

Agents with Drive access can read any file stored in Drive:

1. Configure Agent: Give your agent the Drive tool access
2. Natural Language: Ask your agent to read or process files

Example agent prompts:

• “Read the Q1 report from Drive and summarize key findings”
• “Find all PDF files in /reports and extract the metrics”
• “Download the latest data export and analyze trends”

Writing Files

Agents can also create and write files to Drive:

• “Save the research summary as a PDF to /research folder”
• “Export the contact list to a CSV file in Drive”
• “Write a daily status report to /reports/daily/“

Skills and Long-Term Memory

Drive can support:

• Reusable assets: Prompt templates, checklists or static reference files
• Long-term artifacts: Summaries, logs and generated deliverables that persist across sessions

User: "Remember that our Q1 target is $500K"
Agent: "I've saved that to Drive. I'll remember it for future conversations."

This is useful when memory should be visible and inspectable as files, not hidden in transient context.

Best Practices

• Use descriptive names: Include date or version in generated outputs
• Keep folder conventions stable: Agents perform better with predictable paths
• Separate input and output paths: Example /inbox vs /reports
• Schedule cleanup: Archive old folders to control sprawl
• Use Databases for retrieval-heavy use cases: Keep Drive for file ops

Next Steps

• Drive API Reference: Full endpoint docs and examples
• Agents: Build agents that use Drive as a tool
• Databases: Use semantic search for knowledge retrieval

Built with ❤️ by Scout OS