File Management

1. Navigate to Agents → Select your agent → Edit
2. In the Tools section, enable file management tools
3. Configure file access permissions and allowed paths
4. Save and test the agent with file operations

Example AI Interactions

Listing and Searching Files:

User: Find all PDF files in my documents
AI: [calls list_files with search filter]
AI: Found 5 PDF files in documents/:
• report_2024.pdf (2.3 MB, Modified: 2024-01-15)
• proposal.pdf (1.1 MB, Modified: 2024-01-10)
• contract_final.pdf (892 KB, Modified: 2024-01-08)
• meeting_notes.pdf (456 KB, Modified: 2024-01-05)
• invoice_march.pdf (234 KB, Modified: 2024-01-03)

Content Analysis:

User: Search for files containing "budget" in their content
AI: [calls local_grep or searches file content]
AI: Found 3 files mentioning "budget":
• financial_plan.docx (line 45: "Q4 budget allocation")
• project_proposal.pdf (page 12: "budget constraints")
• meeting_notes.txt (line 23: "discuss budget approval")

File Management:

User: Upload this image and create a gallery post
AI: [calls upload_file, then create_record]
AI: Uploaded image.jpg to images/ (1.2 MB)
Created gallery post "Sunset View" with the uploaded image

Batch Operations:

User: Move all files from temp/ to archive/ and clean up
AI: [calls list_files, move_file in batch]
AI: Moved 12 files from temp/ to archive/2024-q1/
Deleted empty temp/ folder

How to Use

File Operations

• Listing Files: Browse directory contents

  list_files(path="files")
  

• Creating Folders: Organize files in a logical structure

  create_folder(folder_name="project_documents", path="files")
  

• Uploading Files: Add new files to the system

  upload_file(file_name="report.pdf", content_base64="...", path="files/project_documents")
  

• Accessing File Content: Retrieve file information or content

  get_file_content(file_path="files/project_documents/report.pdf")
  

• Moving or Renaming: Reorganize your file structure

  move_file(source_path="files/old_name.pdf", destination_path="files/new_name.pdf", is_folder=false)
  

• Deleting Files: Remove files or folders

  delete_file(file_path="files/project_documents/old_file.pdf", is_folder=false)
  

Programmatic Access

BrightsyClient SDK

The SDK provides comprehensive file management with automatic error handling and TypeScript support:

import { BrightsyClient } from '@brightsy/client';

const client = new BrightsyClient({
  api_key: 'bsy_...',
  account_id: 'account-uuid'
});

// Upload with progress and metadata
const upload = await client.files().upload('report.pdf', fileBuffer, {
  folder: 'documents/quarterly',
  metadata: { category: 'finance', quarter: 'Q4' }
});

// List with filtering and pagination
const files = await client.files().list('documents/', {
  search: 'budget',
  limit: 20,
  sortBy: 'modified',
  sortOrder: 'desc'
});

// Get signed URL for secure access
const signedUrl = await client.files().getSignedUrl('private/document.pdf', {
  expiresIn: 3600  // 1 hour
});

// Stream large files
const stream = await client.files().downloadStream('large-video.mp4');
stream.pipe(fs.createWriteStream('local-copy.mp4'));

// Batch operations
await client.files().moveMultiple([
  { from: 'temp/file1.pdf', to: 'archive/file1.pdf' },
  { from: 'temp/file2.pdf', to: 'archive/file2.pdf' }
]);

// Create organized folder structure
await client.files().createFolder('documents/2024/projects');

Best Practices

Organization & Structure

• Hierarchical Design: Use clear folder structures like documents/contracts/, images/products/, assets/branding/
• Consistent Naming: Use kebab-case for folders (user-uploads) and descriptive filenames
• Metadata Strategy: Leverage file metadata for categorization and search
• Version Control: Use meaningful version names when manually versioning files

Performance & Scalability

• File Size Limits: Be aware of 100MB per file limit; compress large files when possible
• Batch Operations: Use bulk operations for multiple files to reduce API calls
• CDN Optimization: Public files automatically use global CDN for fast delivery
• Lazy Loading: Load file previews and thumbnails on demand

Security & Access Control

• Public vs Private: Store user-generated content as private by default
• Signed URLs: Always use signed URLs for private file access (they expire automatically)
• Permission Levels: Configure appropriate access for different user roles
• Audit Trails: File operations are logged for security monitoring

Integration Patterns

• Record Attachments: Link files to records using file reference fields
• Component Assets: Store component images and assets in organized folders
• Template Resources: Keep reusable assets in dedicated template folders
• Backup Strategy: Important files have automatic version history

AI & Automation

• Smart Organization: Let AI agents help categorize and organize files
• Content Analysis: Use AI to generate descriptions and tags for uploaded files
• Duplicate Detection: Implement checks to prevent duplicate file uploads
• Auto-tagging: Configure rules for automatic metadata assignment

Development Workflow

• Local Development: Use local MCP tools for project file operations
• Version Sync: Keep local development files in sync with platform storage
• Build Assets: Automate upload of build artifacts and assets
• Environment Separation: Use different folders for dev/staging/production assets

Monitoring & Maintenance

• Usage Tracking: Monitor storage usage and set up alerts for limits
• Regular Cleanup: Schedule automated cleanup of temporary and old files
• Backup Verification: Regularly verify backup integrity and accessibility
• Performance Monitoring: Track file access patterns and optimize hot paths