Attachments

Upload files as part of your message — CSVs, images, code, specs, anything. The agent reads them, processes them, and can produce new files in return.

Sending Files

Encode your file as a base64 data URL and include it as a file part alongside your text:

const csv = `month,revenue,users
Jan,42000,1200
Feb,48000,1350
Mar,51000,1580
Apr,61000,1820`;

const csvBase64 = Buffer.from(csv).toString("base64");

const result = await session.send({
    parts: [
        {
            type: "text",
            text: "Analyze this CSV and summarize the trends.",
        },
        {
            type: "file",
            url: `data:text/csv;base64,${csvBase64}`,
            mime: "text/csv",
            filename: "data.csv",
        },
    ],
});

File Part Schema

• type string required — Always "file".
• url string required — A data: URL with the base64-encoded content. Format: data:{mime};base64,{content}.
• mime string required — MIME type of the file (e.g. text/csv, image/png, text/markdown).
• filename string — Display name for the file.

Receiving Files

When the agent produces files (charts, reports, etc.), catch them with the onAttachment callback:

import type { FilePart } from "swarmlord";

const receivedFiles: FilePart[] = [];

await session.send(
    {
        parts: [
            {
                type: "text",
                text: "Create a matplotlib chart from the CSV and save as /workspace/chart.png",
            },
            {
                type: "file",
                url: `data:text/csv;base64,${csvBase64}`,
                mime: "text/csv",
                filename: "data.csv",
            },
        ],
    },
    {
        onText: delta => process.stdout.write(delta),
        onAttachment: file => {
            receivedFiles.push(file);
            console.log(`Received: ${file.filename} (${file.mime})`);
        },
    }
);

Downloading Generated Files

After the agent finishes, pull files directly from the sandbox:

import { writeFileSync } from "fs";

// Text files
const report = await session.getFile("/workspace/report.html");
writeFileSync("output/report.html", report);

// Binary files (images, PDFs, etc.)
const chart = await session.getFileBuffer("/workspace/chart.png");
writeFileSync("output/chart.png", new Uint8Array(chart));

Full Example

Upload a CSV, have the agent create a chart and HTML report, then download both:

import { createClient, type FilePart } from "swarmlord";
import { writeFileSync, mkdirSync } from "fs";

const client = createClient({
    apiKey: process.env.SWARMLORD_API_KEY!,
});

const agent = client.agent({
    name: "build",
    config: { permission: "allow" },
});
const session = await agent.createSession();

const csv = `month,revenue,users
Jan,42000,1200
Feb,48000,1350
Mar,51000,1580
Apr,61000,1820
May,58000,2100
Jun,72000,2450`;

const csvBase64 = Buffer.from(csv).toString("base64");
const received: FilePart[] = [];

await session.send(
    {
        parts: [
            {
                type: "text",
                text:
                    "I've attached a CSV with monthly revenue and user data. " +
                    "1) Summarize the trends. " +
                    "2) Create a matplotlib chart saved as /workspace/chart.png. " +
                    "3) Create /workspace/report.html with the summary.",
            },
            {
                type: "file",
                url: `data:text/csv;base64,${csvBase64}`,
                mime: "text/csv",
                filename: "data.csv",
            },
        ],
    },
    {
        onText: delta => process.stdout.write(delta),
        onAttachment: file => received.push(file),
    }
);

// Download results
mkdirSync("output", { recursive: true });

const chart = await session.getFileBuffer("/workspace/chart.png");
writeFileSync("output/chart.png", new Uint8Array(chart));

const report = await session.getFile("/workspace/report.html");
writeFileSync("output/report.html", report);

console.log(`\nDownloaded ${received.length} attachments`);

await session.end();