File Attachments

Upload files, images, and documents to include them in agent conversations. The SDK handles compression, two-phase uploads, and progress tracking.

Quick Start

tsx

<AgentChat
  agentId="agent-uuid"
  enableAttachments  // That's it!
/>

Users can drag & drop files, click the attachment button, or paste images.

Supported Files

Category	Extensions	Max Size
Document	PDF, DOCX, TXT, MD, CSV, XLSX	25 MB
Image	PNG, JPG, GIF, WEBP, SVG	10 MB
Audio	MP3, WAV, M4A, OGG, WEBM	50 MB

Upload Flow

1. Request upload URL → POST /api/attachments/upload

Returns: { uploadUrl, attachmentUuid }

2. Upload to S3 → PUT {uploadUrl}

3. Confirm upload → POST /api/attachments/{uuid}/confirm

4. Send with message → attachmentIds: [uuid]

useFileAttachments Hook

tsx

import { useFileAttachments, FileDropZone } from '@cadraos/sdk/chat';

const attachments = useFileAttachments({
  onUpload: async (file, metadata) => {
    const res = await fetch('/api/attachments/upload', {
      method: 'POST',
      body: JSON.stringify(metadata),
    });
    return res.json(); // { uuid, uploadUrl }
  },
  onConfirmUpload: async (uuid) => {
    await fetch(`/api/attachments/${uuid}/confirm`, { method: 'POST' });
  },
  maxFiles: 10,
  maxTotalSizeMB: 100,
});

// Spread props onto FileDropZone
<FileDropZone {...attachments.dropZoneProps}>
  <div>Your chat UI here</div>
</FileDropZone>

// On send
const uuids = attachments.getReadyUuids();
await sendMessage(text, { attachmentUuids: uuids });
attachments.clear();

Server-Side Attachments

typescript

await client.agents.execute('agent-uuid', {
  task: 'Analyze the uploaded documents',
  attachmentIds: ['uuid-1', 'uuid-2'],
});