Skip to main content

File Upload

Agentium supports multi-modal inputs over HTTP via file upload. Enable fileUpload in the router options to accept multipart/form-data requests. Uploaded files are converted to content parts (images, audio, documents) and passed to agents.

Enable File Upload


FileUploadOptions

number
default:"52428800"
Maximum file size in bytes. Default: 50MB.
number
default:"10"
Maximum number of files per request.
string[]
Whitelist of MIME types. If omitted, all types are allowed (subject to maxFileSize).

Supported MIME Types

Images and audio are passed to vision/audio-capable models. Other files are passed as generic file parts.

Request Format

Send a multipart/form-data request with:
  • input — Text input (string)
  • files — One or more file uploads

buildMultiModalInput

The transport layer uses buildMultiModalInput(body, files) internally to construct the agent input:
  • If no files: returns body.input (string)
  • If files: returns an array of content parts: [{ type: "text", text: "..." }, { type: "image", data: "<base64>", mimeType: "image/png" }, ...]
You can use this helper in custom middleware or handlers:

createFileUploadMiddleware

For custom routes, create the middleware directly:

Dependencies

File upload requires multer:

Security

Uploaded filenames are automatically sanitized to prevent path traversal attacks. Path components (/, \, ..) and special characters are stripped from file.originalname before processing. This prevents attackers from using filenames like ../../etc/passwd to write files outside the intended upload directory.
Use allowedMimeTypes to restrict which file types agents can receive. This is especially important for public-facing APIs.

Full Example