# How Swarmates.ai Works

> Every agent. One swarm.
>
> The coordination layer where every kind of AI agent joins forces, shares context, and works together.

---

## The mental model

Think of Swarmates.ai as **a coordination layer for your AI agents**.

Every AI agent you use lives in its own silo today: Abacus AI has its chat window, ChatGPT has its own, Claude has another, your custom webhook agent is off in yet another place. They can't see each other. They can't share context. You end up copy-pasting between ten tabs.

Swarmates.ai is the coordination layer that connects them into one swarm. **Every agent joins the swarm.** GPT, Claude, Abacus, your internal models — whatever you use. Once they're in the swarm they can talk to each other, share what they know, and divide the labour on the tasks you set.

The metaphor is literal. In biology, a swarm is smarter than any individual creature in it. Scout bees find flowers, workers harvest, the colony routes information through dances. Your agents work the same way when they can see each other: specialist skills compound, outputs flow downstream, and what used to take five tabs takes one prompt.

---

## The four building blocks

Everything you do on Swarmates.ai is a combination of four things:

### 1. Agents
An agent is any AI service you can call. Swarmates.ai ships with four native adapter types:

- **Abacus adapter**, for Abacus.AI ChatLLM and custom agent deployments
- **OpenAI adapter**, for anything that speaks `POST /v1/chat/completions`
- **Claude adapter**, for Anthropic Claude directly
- **Webhook adapter**, for anything else: your internal agent, a SaaS with a plain POST endpoint, etc.

Every adapter implements the same three methods: `ping` (check health), `query` (send a prompt, get a reply), and `stream` (optional SSE streaming). Adding a new adapter (say, Gemini) is about 80 lines of code.

### 2. Context
Context is shared memory. Files, notes, URLs, structured schemas, anything the swarm needs to know. You pick **which agents can see which context item**. Nothing is shared automatically. When an automation fires and Agent B is invoked, Swarmates.ai bundles the context items Agent B has access to into the prompt for that call. This is how Agent B "knows" what Agent A was working with.

### 3. Connections
A connection is a permission and an audit trail in one. "Agent A may call Agent B" becomes a connection. Every call flowing through the connection is a message: payload in, response out, tokens consumed, latency, timestamp. The activity feed shows all of this live, via Server Sent Events.

### 4. Automations
Automations are the "when this, do that" layer. They have triggers (manual, schedule, agent event, webhook) and actions (query another agent with chosen context, fan out to multiple, run a webhook). They have a dry-run mode so you can preview the flow without burning real API calls.

---

## The five-minute story

Here is what a first run looks like, end to end:

1. **Sign up.** The Free plan lets you run two agents forever. No card.
2. **Add your agents.** A four-step wizard: pick type, paste credentials, name it, test the connection live. We ping the provider in the browser so you see if it works before you save.
3. **Share context.** Drop a file or paste a doc into the Context library. Attach it to one or more agents. It's encrypted at rest, served via presigned S3 URLs at call time.
4. **Build an automation.** "When Agent A produces output X, send it to Agent B with context Y." The builder has a template field, voice-input enabled, and a live prompt preview.
5. **Flip it live.** Dry-run once. Everything green? Enable. The activity feed shows every call in real time, including tokens, latency, and the full payload.

Your team, or your stack, now has a swarm of agents collaborating. No glue code.

---

## Technical architecture

The stack is boring on purpose. Boring is reliable.

- **Next.js 14 App Router**, deployed on Abacus.AI's hosting
- **Postgres + Prisma** for the core schema (users, agents, connections, messages, context, automations, events)
- **S3** for uploaded context files, presigned URLs for both upload and read
- **NextAuth** for auth (email + password, Google SSO when configured)
- **Server Sent Events** (`/api/events`) for the live activity feed
- **AES-256-GCM** for every encrypted secret
- **Stripe** for billing (Free, Pro, Team, Enterprise tiers)

Everything agent-facing goes through the **adapter pattern**: a `query(ctx, input)` signature that every adapter implements. The rest of Swarmates.ai doesn't care if the agent is OpenAI or a cron job behind a webhook. It all looks the same from the swarm.

---

## The adapter contract

Every adapter file exports three functions:

```ts
export const myAdapter: AgentAdapter = {
  type: "my-provider",
  async ping(ctx)          { /* health check */ },
  async query(ctx, input)  { /* send prompt, return reply */ },
  async stream?(ctx, input, onChunk) { /* optional streaming */ },
}
```

That's it. All four built-in adapters (`abacus`, `openai`, `claude`, `webhook`) follow this pattern. A new one is a single file in `lib/adapters/` plus an entry in `lib/adapters/registry.ts`.

---

## Security posture

- **AES-256-GCM** for all API keys at rest. Derived key, never co-located with the ciphertext.
- **Per-user isolation** at the database layer. Every Prisma query filters by `userId`. There is no cross-tenant code path.
- **Encrypted vault pattern.** Raw keys never leave the server after first write. The browser never decrypts a key.
- **Signed uploads.** Uploaded context files go straight from the browser to S3 via a presigned URL. The server only sees the `cloud_storage_path`, never the file body.
- **Audit log.** Every message, every automation run, every context access is recorded with timestamp and user.
- **Optional Google SSO.** The Free plan works with email and password; organisations can require SSO.

---

## Voice prompting

Swarmates.ai supports **voice input** on every text field that matters: agent descriptions, context notes, automation prompts, and the agent chat box.

### How it works

- Click the microphone next to any supported field.
- Speak. The browser's built-in Web Speech API transcribes locally, on your device.
- Click the microphone again to stop. Your speech is never sent to Swarmates.ai servers. No extra cost. No latency hop.

### Supported languages

Voice input automatically follows your UI language. Swarmates.ai ships with English, Spanish, French, German, Chinese, Japanese, and Portuguese. BCP-47 tags (`en-US`, `es-ES`, `fr-FR`, `de-DE`, `zh-CN`, `ja-JP`, `pt-BR`) are derived automatically.

### Browser support

Works in any Chromium-based browser (Chrome, Edge, Arc, Brave) and desktop Safari. If a browser doesn't support the Web Speech API (Firefox, some mobile browsers), the mic button simply does not appear. The text field still works normally.

---

## Use cases

### Draft to CMS pipeline (marketing)
Agent A (GPT-4o) writes a blog draft. Agent B (Claude) proofreads and flags facts. A webhook publishes the approved draft to your CMS. A swarm of three, working as one.

### Auto ticket triage (support)
Your chat agent collects a ticket. An OpenAI agent classifies it as bug, billing, or how-to. A webhook creates the ticket in Zendesk with the right tags. Specialist agents, one coordinated output.

### Dataset copilot (data)
A dataset lands in the Context library. Claude summarises the schema. A code agent writes the ETL and opens a PR on GitHub. Each agent does the part it is best at.

---

## Pricing (at a glance)

| Plan       | Agents | Messages | Cost     |
|------------|--------|----------|----------|
| Free       | 2      | 100 / mo | $0       |
| Pro        | 10     | 5,000    | $29 / mo |
| Team       | 50     | 50,000   | $99 / mo |
| Enterprise | custom | custom   | Talk to us |

Stripe handles all payment flow. Upgrading or downgrading takes one click.

---

## Philosophy

We built Swarmates.ai because we were the teams living in 12 chat tabs. Tiny context switches were eating whole afternoons.

Every agent. One swarm. A single place where every agent can work with every other agent, under rules you set, with an audit trail you can read. No scraping. No glue code. No vendor lock in. Just collective intelligence, on tap.

Start your swarm with two agents and watch the compounding begin.

*Need help? Email hello@Swarmates.ai. We read everything and reply fast.*