Quickstart

Build a data-analyst agent that compares this year's data against last year's — producing styled charts and a year-over-year report.

1. Get an API Key

Sign up at swarmlord.ai and create an API key from the dashboard.

export SWARMLORD_API_KEY="slsk_your_key_here"

Or use the CLI to store credentials interactively:

swarmlord auth login

2. Scaffold an Agent

npm

npm install -g swarmlord
swarmlord init data-analyst

npx (no install)

npx swarmlord init data-analyst

bun

bunx swarmlord init data-analyst

This creates:

data-analyst/
├── swarmlord.jsonc   # Agent config (model, tools)
├── SOUL.md         # Always-loaded instructions
├── skills/           # On-demand knowledge (loaded via skill tool)
│   └── example/
│       └── SKILL.md
├── files/            # Pre-loaded workspace files
└── .gitignore

Each session runs in a cloud sandbox where /workspace/ is the root directory. Everything in files/ is loaded there at session start.

3. Write Your Instructions

Edit SOUL.md — this is the agent's system prompt, loaded every session:

# Data Analyst

You analyze datasets and produce clear, publication-quality charts and reports.
Historical data lives in `/workspace/data/` — users may attach new data for comparison.

## Workflow

1. Read all available datasets and understand their structure
2. Load the **chart-style** skill before creating any visualizations
3. If comparing periods, align the data by shared columns (e.g. month)
4. Create charts using Python (matplotlib) following the style guide
5. Write a report to `/workspace/report.md` with your findings

## Guidelines

- Always load the chart-style skill before plotting
- Save charts as PNG to `/workspace/` with descriptive names
- Include specific numbers and percentages
- When comparing year-over-year, show both lines on the same chart

4. Add a Skill

Replace the example skill with a chart style guide. Create skills/chart-style/SKILL.md:

---
name: chart-style
description: Visual style guide for all charts — colors, fonts, layout rules
---

# Chart Style Guide

## Colors

Use this palette in order:

```python
COLORS = ["#4F46E5", "#10B981", "#F59E0B", "#EF4444", "#8B5CF6", "#06B6D4"]
```

## Layout

```python
fig, ax = plt.subplots(figsize=(10, 6))
fig.patch.set_facecolor("#0F172A")
ax.set_facecolor("#0F172A")
ax.spines["top"].set_visible(False)
ax.spines["right"].set_visible(False)
```

- Dark background (`#0F172A`), light text (`#F8FAFC`)
- Remove top and right spines
- Subtle gridlines, 150 dpi, `bbox_inches="tight"`

Skills are loaded on-demand — the agent sees the skill names and descriptions in its tool list, and loads the full content only when it's relevant.

5. Add Historical Data

Create files/data/sales-2025.csv — everything under files/ becomes available at /workspace/ in the sandbox:

mkdir -p files/data

files/
└── data/
    └── sales-2025.csv

month,revenue,users,churn_rate
Jan,28000,600,5.1
Feb,31000,680,4.8
Mar,33000,750,4.5
...
Dec,55000,1500,2.4

Users will attach this year's data at runtime for comparison.

6. Test It

swarmlord run creates a one-off cloud session from your local directory without deploying — useful for iterating on instructions and skills:

cd data-analyst
swarmlord run "List the files in /workspace/data/ and summarize the dataset"

The CLI bundles your config, instructions, skills, and files, executes the session, streams the response, and cleans up. See the CLI Reference for details.

7. Deploy

swarmlord deploy

The CLI bundles your config, instructions, skills, and files, then deploys. On success you'll see the agent name and a SDK usage hint:

data-analyst deployed
  Use: client.agent("data-analyst").createSession()

The agent is now addressable by name from the SDK. You can attach webhook triggers or a cron schedule later.

8. Use It

Create a session from the TypeScript SDK — attach this year's data and let the agent compare it against last year's:

import { readFileSync } from "node:fs";
import { createClient } from "swarmlord";

const csvBase64 = readFileSync("sales-2026.csv").toString("base64");

const client = createClient();
const session = await client.agent("data-analyst").createSession();

await session.send(
    {
        parts: [
            {
                type: "text",
                text: "I've attached 2026 sales data. Last year's is at /workspace/data/sales-2025.csv. Compare the two years.",
            },
            { type: "file", url: `data:text/csv;base64,${csvBase64}`, mime: "text/csv", filename: "sales-2026.csv" },
        ],
    },
    { onText: delta => process.stdout.write(delta) }
);

const chart = await session.getFileBuffer("/workspace/revenue-yoy.png");

The agent loads the chart-style skill, reads both CSVs, produces styled charts with matplotlib, and writes a report — all in an isolated cloud sandbox.

Next Steps

CLI Reference

Full config format, skills system, and all CLI commands.

Tools

14 built-in tools — including the skill tool for on-demand knowledge.