File Upload Messaging¶

Why a Dedicated File Type?¶

Users often need to send documents, images, or other files to an agent — an invoice to process, a photo to analyze. Files don't fit the chat or data message model: they are large binary payloads that would blow past Temporal's ~2 MB signal limit if sent inline. So Xians treats files as a first-class message type (File) with its own handler, storage, and delivery pipeline:

sequenceDiagram
    participant C as Client app
    participant S as Xians Server
    participant G as GridFS storage
    participant A as Agent (OnFileUpload)

    C->>S: POST /send/file (base64 files)
    S->>G: Store file bytes (tenant-scoped)
    S->>A: Signal with lightweight references only
    A->>G: SDK downloads bytes transparently
    Note over A: context.Message.Files has decoded bytes
    A-->>C: ReplyAsync("File received!")

The key idea: clients send base64, the server stores bytes in MongoDB GridFS, and only tiny references travel through Temporal. Your handler still sees the full file content — the SDK downloads it for you before the handler runs.

Handling File Uploads in Your Agent¶

Register OnFileUpload on a built-in workflow. Files arrive as typed UploadedFile objects via context.Message.Files — no JSON parsing or manual downloads needed:

var conversationalWorkflow = xiansAgent.Workflows.DefineSupervisor();

conversationalWorkflow.OnFileUpload(async (context) =>
{
    var files = context.Message.Files;

    if (files.Count == 0)
    {
        await context.ReplyAsync("No file data received.");
        return;
    }

    foreach (var file in files)
    {
        if (!file.TryGetBytes(out var fileBytes))
        {
            await context.ReplyAsync($"Invalid file format for '{file.FileName}'.");
            return;
        }

        // Process fileBytes using file.FileName, file.ContentType...
        await context.ReplyAsync($"Received {file.FileName} ({fileBytes!.Length} bytes)");
    }
});

The handler receives the same UserMessageContext as chat handlers, so ReplyAsync, SendDataAsync, and GetChatHistoryAsync all work as usual. An optional caption sent by the client is in context.Message.Text.

The UploadedFile Type¶

Accepted Payload Formats¶

context.Message.Files decodes every wire format a File message can arrive in. You normally don't care which one was used — the result is always a list of UploadedFile:

Unrecognizable data yields an empty list — it never throws.

Sending Files from Client Applications¶

Use the specialized file endpoint of the Messaging Admin API:

POST /api/v1/admin/tenants/{tenantId}/messaging/send/file

Request Fields¶

Limits¶

Violations are rejected with 400 Bad Request.

Example¶

curl -X POST "https://your-server/api/v1/admin/tenants/default/messaging/send/file" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "DocumentAgent",
    "activationName": "DocumentAgent - Default",
    "participantId": "user@example.com",
    "text": "Here are the invoice and the receipt.",
    "files": [
      { "content": "JVBERi0x...", "fileName": "invoice.pdf", "contentType": "application/pdf" },
      { "content": "iVBORw0K...", "fileName": "receipt.png", "contentType": "image/png" }
    ],
    "topic": "document-uploads"
  }'

The tenant can be given in the URL path or via the X-Tenant-Id header.

Downloading Stored Files¶

Stored messages carry references, not bytes, so message history and SSE streams stay lightweight. Fetch content on demand — both endpoints enforce tenant isolation:

Agents rarely call the download endpoint directly — context.Message.Files already resolves bytes for you. Agent Studio renders file attachments as download links automatically.

Summary¶