File Uploads

The Client SDK supports uploading images and documents that can be sent with messages. This enables vision model capabilities (analyzing images) and document processing.

Overview

File uploads follow a two-step flow:

1. Request upload URLs from the platform via your backend
2. Upload files directly to S3 using presigned URLs
3. Send file references with your message

This architecture keeps your API key secure on the server while enabling fast, direct uploads.

Setup

Backend: Upload URLs Endpoint

Create an endpoint that proxies upload URL requests to the Octavus platform:

Client: Configure File Uploads

Pass requestUploadUrls to the chat hook:

Uploading Files

Method 1: Upload Before Sending

For the best UX (showing upload progress), upload files first, then send:

Method 2: Upload on Send (Automatic)

For simpler implementations, pass File objects directly:

The SDK automatically uploads the files before sending. Note: This doesn't provide upload progress.

Upload Reliability

Uploads include built-in timeout and retry logic for handling transient failures (network errors, server issues, mobile network switches).

Default behavior:

• Timeout: 60 seconds per file - prevents uploads from hanging on stalled connections
• Retries: 2 automatic retries on transient failures (network errors, 5xx, 429)
• Retry delay: 1 second between retries
• Non-retryable errors (4xx like 403, 404) fail immediately without retrying

Only the S3 upload is retried - the presigned URL stays valid for 15 minutes. On retry, the progress callback resets to 0%.

Configure via uploadOptions:

To disable timeout or retries:

Using OctavusChat Directly

When using the OctavusChat class directly (without the React hook), pass uploadOptions in the constructor:

FileReference Type

File references contain metadata and URLs:

Protocol Integration

To accept files in your agent protocol, use the file[] type:

The file type is a built-in type representing uploaded files. Use file[] for arrays of files.

Supported File Types

Images, video, PDFs, and text-based formats are sent directly to the model as file parts. Office documents are not natively readable by LLM providers, so they are surfaced to the agent as presigned download URLs - the agent fetches and parses them with code or skills (e.g. via a sandboxed computer).

File Limits

Rendering User Files

User-uploaded files appear as UIFilePart in user messages:

Server SDK: Files API

The Server SDK provides direct access to the Files API:

Complete Example

Here's a full chat input component with file upload: