Skip to main content

​
File Handling & Uploads

Savant supports multiple ways to work with files — from inline attachments in messages to the server-side file storage API for large-file multimodal processing.

​
File Upload Methods

MethodBest ForMax SizeHow It Works
Inline textSmall text files (< 100KB)~100KBSent as text in the message body
Inline base64Small binary files (< 20MB)~20MBBase64-encoded in the message body
File storage APILarge files (up to 2GB)2GBUploaded to model provider, referenced by URI
Artifact uploadSession-scoped storage20MBStored in-memory, accessible via tools

​
Inline File Attachments

Send files directly as A2A DataPart content in your POST /send message, or via the REST API:

​
Text Files

{
    "message": "Analyze this configuration",
    "session_id": "session-1",
    "files": [{
        "name": "config.json",
        "mime_type": "application/json",
        "size": 1024,
        "content": "{ \"key\": \"value\" }"
    }]
}

​
Binary Files (Base64)

{
    "message": "What does this image show?",
    "session_id": "session-1",
    "files": [{
        "name": "screenshot.png",
        "mime_type": "image/png",
        "size": 204800,
        "data": "iVBORw0KGgoAAAANS..."
    }]
}

​
File Storage API

For large files or when you want native multimodal processing:

​
Step 1: Upload the File

Via API: 
curl -X POST http://localhost:3000/files/upload \
  -F "file=@./document.pdf"
Via SDK: 
const ref = await session.upload_file_to_storage(
    fs.readFileSync('./document.pdf'),
    'document.pdf',
    'application/pdf',
);
// ref.file_uri → file storage URI for use in messages
Via Base64: 
curl -X POST http://localhost:3000/files/upload-base64 \
  -H "Content-Type: application/json" \
  -d '{
    "data": "JVBERi0xLjQ...",
    "mime_type": "application/pdf",
    "name": "document.pdf"
  }'

​
Step 2: Reference in a Message

{
    "message": "Summarize this insurance policy",
    "session_id": "session-1",
    "files": [{
        "name": "policy.pdf",
        "mime_type": "application/pdf",
        "size": 1048576,
        "file_uri": "https://generativelanguage.googleapis.com/v1beta/files/abc123"
    }]
}
Via SDK: 
const stream = session.send_with_files('Summarize this policy', [{
    name: 'policy.pdf',
    mime_type: 'application/pdf',
    size: 1048576,
    file_uri: ref.file_uri,
}]);

​
Artifact Uploads

Artifacts are session-scoped file storage. Agents can access artifacts using the read_artifact tool.

​
Upload

curl -X POST http://localhost:3000/upload \
  -F "file=@./data.csv" \
  -F "user_id=my-user" \
  -F "session_id=session-1"
Via SDK: 
const result = await session.upload_file(
    fs.readFileSync('./data.csv'),
    'data.csv',
    'text/csv',
);

​
Response

{
    "success": true,
    "artifact_name": "data.csv",
    "mime_type": "text/csv",
    "size": 2048,
    "version": 0,
    "session_id": "session-1"
}

​
Supported Artifact Types

CategoryMIME Types
Imagesimage/jpeg, image/png, image/gif, image/webp
Documentsapplication/pdf
Datatext/plain, text/csv, application/json

​
How Files Reach the Agent

When files are included in a message, they become Content Parts in the agent conversation:
Attachment TypePart Type
Text contenttext part (with filename header)
Base64 datainlineData part (native multimodal)
File storage URIfileData part (fastest, no tool calls needed)
Artifact reftext part (agent uses read_artifact tool to access)
The foundation model processes images and PDFs natively — no OCR or extraction tools are needed for basic understanding.