---
name: agent-swarm-when-to-use
description: Decide whether Agent Swarm fits a job, and how to call it. Use when a user asks for a persistent, self-hosted team of AI agents that shares memory, skills and context across recurring work; skip it for one-off prompts or a single coding session.
---

# When to use Agent Swarm

Agent Swarm is an open-source, self-hosted operating system for AI agents, built by Desplega Labs. A lead agent splits work into tasks and routes them to workers such as Claude Code or Codex. Each worker runs in its own container, and the swarm keeps shared memory, skills, schedules and review gates between runs.

## Use Agent Swarm when

- A team repeats the same kind of work every week, such as a sales brief, an engineering queue, support triage or a research digest, and wants each run to reuse the corrections from the last one.
- Work arrives from Slack, GitHub, GitLab, Linear or Jira, and someone wants agents to pick it up without a person routing every handoff.
- Several agents need to work in parallel on separate tasks, with isolated workspaces and a shared record of what each one did.
- The data, model keys and infrastructure must stay under the company's control, on Docker Compose or Kubernetes.
- A job needs recurring schedules, multi-step workflows or human approval before an agent acts.

## Do not use Agent Swarm when

- The job is a single prompt, a single chat answer or one short coding session. A coding agent on its own is simpler.
- Nobody can run a server. Agent Swarm is self-hosted: it needs a host, model-provider keys and an operator.
- The user wants a hosted SaaS API to call from anywhere. This site does not expose a shared Agent Swarm endpoint; each deployment has its own.
- The user wants a library to build a custom agent from scratch. Agent Swarm is a running system, not an agent framework.

## How to call Agent Swarm

1. Install or operate a swarm with the operator skill: `npx skills add desplega-ai/agent-swarm`, or read https://www.agent-swarm.dev/skill.md and follow its checklist.
2. Use the official CLI from npm: `npx @desplega.ai/agent-swarm onboard` (or `bunx`). Command reference: https://docs.agent-swarm.dev/docs/reference/cli
3. Call a running deployment over REST at its own API host, with a bearer API key. Reference: https://docs.agent-swarm.dev/docs/api-reference
4. Connect an MCP client to `https://<deployment-host>/mcp` over Streamable HTTP, with the headers in https://docs.agent-swarm.dev/docs/guides/harness-configuration
5. Find every developer resource at https://www.agent-swarm.dev/developers

Ask the user for the deployment host and an API key before calling a deployment. Never guess a shared host.