Build a Multi-Agent Backend in Node.js and TypeScript with the Swarms API

// lib/swarms.ts
// A small typed client for the Swarms API. No SDK, no dependencies: fetch is
// built into Node 18+, Bun, Deno and every edge runtime.

export const SWARMS_API_URL = "https://api.swarms.world"

export type SwarmType =
  | "SequentialWorkflow"
  | "ConcurrentWorkflow"
  | "HierarchicalSwarm"
  | "MixtureOfAgents"
  | "MajorityVoting"
  | "GroupChat"
  | "AgentRearrange"
  | "MultiAgentRouter"
  | "CouncilAsAJudge"
  | "HeavySwarm"
  | "LLMCouncil"
  | "DebateWithJudge"
  | "RoundRobin"
  | "PlannerWorkerSwarm"

export type AgentSpec = {
  agent_name: string
  system_prompt: string
  model_name?: string
  description?: string
  max_loops?: number
  max_tokens?: number
  temperature?: number
}

export type SwarmRequest = {
  name: string
  description?: string
  swarm_type: SwarmType
  task: string
  agents: AgentSpec[]
  max_loops?: number
  rearrange_flow?: string
  stream?: boolean
}

export type SwarmMessage = { role: string; content: string }

export type SwarmUsage = {
  input_tokens: number
  output_tokens: number
  total_tokens: number
  total_cost: number
  billing_info?: {
    cost_breakdown: {
      agent_cost: number
      input_token_cost: number
      output_token_cost: number
      num_agents: number
    }
  }
}

export type SwarmResponse = {
  job_id: string
  status: string
  swarm_name: string
  swarm_type: SwarmType
  output: SwarmMessage[]
  number_of_agents: number
  execution_time: number
  usage: SwarmUsage
}

export class SwarmsError extends Error {
  status: number
  body: string

  constructor(status: number, body: string) {
    super(`Swarms API ${status}: ${body}`)
    this.name = "SwarmsError"
    this.status = status
    this.body = body
  }
}

export async function runSwarm(
  request: SwarmRequest,
  apiKey: string | undefined = process.env.SWARMS_API_KEY,
): Promise<SwarmResponse> {
  if (!apiKey) throw new Error("SWARMS_API_KEY is not set")

  const res = await fetch(`${SWARMS_API_URL}/v1/swarm/completions`, {
    method: "POST",
    headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
    body: JSON.stringify({ ...request, stream: false }),
  })

  if (!res.ok) throw new SwarmsError(res.status, await res.text())
  return (await res.json()) as SwarmResponse
}

/** Opens a streaming run and returns the raw Server-Sent Events body. */
export async function streamSwarm(
  request: SwarmRequest,
  apiKey: string | undefined = process.env.SWARMS_API_KEY,
): Promise<Response> {
  if (!apiKey) throw new Error("SWARMS_API_KEY is not set")

  return fetch(`${SWARMS_API_URL}/v1/swarm/completions`, {
    method: "POST",
    headers: {
      "x-api-key": apiKey,
      "Content-Type": "application/json",
      "X-Accel-Buffering": "no",
    },
    body: JSON.stringify({ ...request, stream: true }),
  })
}

// lib/brief-swarm.ts
import type { SwarmRequest } from "./swarms.ts"

// One function builds the request, so the CLI, the JSON route and the
// streaming route all run exactly the same swarm.
export function briefSwarm(topic: string): SwarmRequest {
  return {
    name: "Market Brief Desk",
    swarm_type: "SequentialWorkflow",
    task:
      `Write a competitive brief on ${topic}. Cover market size, three main ` +
      "competitors, key risks and a recommendation. Keep it under 500 words.",
    max_loops: 1,
    agents: [
      {
        agent_name: "Researcher",
        system_prompt:
          "You are a market researcher. List the facts, figures and competitor details relevant to the task as concise bullet points. Do not write the brief.",
        model_name: "gpt-5.4-mini",
        max_loops: 1,
        max_tokens: 1200,
      },
      {
        agent_name: "Analyst",
        system_prompt:
          "You are a strategy analyst. Turn the research into structured findings: market size, competitors, risks, and a recommendation with reasoning.",
        model_name: "claude-haiku-5-5",
        max_loops: 1,
        max_tokens: 1200,
      },
      {
        agent_name: "Writer",
        system_prompt:
          "You are a business writer. Write the final brief under 500 words with the sections: Market size, Main competitors, Key risks, Recommendation.",
        model_name: "claude-sonnet-5-5",
        max_loops: 1,
        max_tokens: 1500,
      },
    ],
  }
}

// scripts/run.ts
// Run with: SWARMS_API_KEY=... node scripts/run.ts "shared e-scooters in Berlin"
import { briefSwarm } from "../lib/brief-swarm.ts"
import { runSwarm } from "../lib/swarms.ts"

const topic = process.argv[2] ?? "shared e-scooters in Berlin"
const result = await runSwarm(briefSwarm(topic))

for (const step of result.output) {
  console.log(`\n## ${step.role}\n${step.content}`)
}

const { total_tokens, total_cost } = result.usage
console.log(`\n${result.number_of_agents} agents, ${result.execution_time.toFixed(1)}s, ${total_tokens} tokens, $${total_cost.toFixed(4)}`)

export SWARMS_API_KEY=your_key
node scripts/run.ts "shared e-scooters in Berlin"

// app/api/brief/route.ts
import { NextResponse } from "next/server"

import { briefSwarm } from "@/lib/brief-swarm"
import { runSwarm, SwarmsError } from "@/lib/swarms"

// A three-agent swarm takes 15 to 30 seconds. Vercel's default function
// timeout is shorter than that on some plans, so raise it explicitly.
export const maxDuration = 60

export async function POST(req: Request) {
  const { topic } = (await req.json().catch(() => ({}))) as { topic?: string }

  if (!topic || topic.length > 300) {
    return NextResponse.json({ error: "topic is required (max 300 characters)" }, { status: 400 })
  }

  try {
    const result = await runSwarm(briefSwarm(topic))
    const brief = result.output.at(-1)?.content ?? ""

    return NextResponse.json({
      brief,
      steps: result.output,
      seconds: result.execution_time,
      cost: result.usage.total_cost,
    })
  } catch (err) {
    if (err instanceof SwarmsError) {
      // 429 is the only upstream status worth passing through unchanged: it
      // tells the client to back off. Everything else is our problem.
      const status = err.status === 429 ? 429 : 502
      return NextResponse.json({ error: err.body }, { status })
    }
    throw err
  }
}

pnpm dev
curl -X POST http://localhost:3000/api/brief \
  -H "Content-Type: application/json" \
  -d '{"topic": "shared e-scooters in Berlin"}'

// app/api/brief/stream/route.ts
import { briefSwarm } from "@/lib/brief-swarm"
import { streamSwarm } from "@/lib/swarms"

export const maxDuration = 60

export async function POST(req: Request) {
  const { topic } = (await req.json().catch(() => ({}))) as { topic?: string }

  if (!topic || topic.length > 300) {
    return Response.json({ error: "topic is required (max 300 characters)" }, { status: 400 })
  }

  const upstream = await streamSwarm(briefSwarm(topic))

  if (!upstream.ok || !upstream.body) {
    return new Response(await upstream.text(), { status: upstream.status })
  }

  // Pass the Server-Sent Events through untouched. The browser never sees
  // the API key, and the route holds nothing in memory.
  return new Response(upstream.body, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache, no-transform",
      Connection: "keep-alive",
      "X-Accel-Buffering": "no",
    },
  })
}

// components/brief-stream.tsx
"use client"

import { useState } from "react"

type ChunkEvent = { agent: string; content: string }
type UsageEvent = { total_cost: number; total_tokens: number }
type ErrorEvent = { error: string }

export function BriefStream() {
  const [topic, setTopic] = useState("shared e-scooters in Berlin")
  const [byAgent, setByAgent] = useState<Record<string, string>>({})
  const [status, setStatus] = useState("idle")

  async function run() {
    setByAgent({})
    setStatus("running")

    const res = await fetch("/api/brief/stream", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ topic }),
    })

    if (!res.ok || !res.body) {
      setStatus(`error ${res.status}`)
      return
    }

    const reader = res.body.getReader()
    const decoder = new TextDecoder()
    let buffer = ""
    let event = "message"

    while (true) {
      const { value, done } = await reader.read()
      if (done) break

      buffer += decoder.decode(value, { stream: true })
      const lines = buffer.split("\n")
      buffer = lines.pop() ?? ""

      for (const line of lines) {
        if (line.startsWith("event:")) {
          event = line.slice("event:".length).trim()
          continue
        }
        if (!line.startsWith("data:")) continue

        const data: unknown = JSON.parse(line.slice("data:".length))

        if (event === "chunk" && isChunk(data)) {
          // Every chunk names the agent that produced it, so the UI can keep
          // one panel per agent even when two of them stream at once.
          setByAgent((prev) => ({ ...prev, [data.agent]: (prev[data.agent] ?? "") + data.content }))
        } else if (event === "usage") {
          const usage = data as UsageEvent
          setStatus(`done: ${usage.total_tokens} tokens, $${usage.total_cost.toFixed(4)}`)
        } else if (event === "error") {
          setStatus((data as ErrorEvent).error)
        }
      }
    }
  }

  return (
    <div className="space-y-4">
      <div className="flex gap-2">
        <input
          className="flex-1 rounded border border-white/20 bg-black px-3 py-2"
          value={topic}
          onChange={(e) => setTopic(e.target.value)}
        />
        <button className="rounded bg-white px-4 py-2 text-black" onClick={run} disabled={status === "running"}>
          Run swarm
        </button>
      </div>
      <p className="font-mono text-xs text-white/60">{status}</p>
      {Object.entries(byAgent).map(([agent, text]) => (
        <section key={agent}>
          <h3 className="font-semibold">{agent}</h3>
          <pre className="whitespace-pre-wrap text-sm text-white/80">{text}</pre>
        </section>
      ))}
    </div>
  )
}

function isChunk(data: unknown): data is ChunkEvent {
  return typeof data === "object" && data !== null && "agent" in data && "content" in data
}

vercel env add SWARMS_API_KEY
vercel --prod

npx create-next-app@latest brief-desk --ts --app
cd brief-desk
export SWARMS_API_KEY=your_key