Skip to content

Concepts#

swarm is built around seven ideas. If you understand these, the how-to guides, reference, and compliance docs will feel familiar rather than surprising.

  • What is swarm?

    The one-paragraph pitch + where we fit in the landscape.

  • Agents & teams

    40 agents across 7 teams; when to use which.

  • Pipelines

    Declarative YAML, three built-in templates, parallel vs sequential execution.

  • Tools & plugins

    38 built-in tools + Claude Code marketplace plugin compat.

  • Permissions & audit

    Unified ALLOW > DENY > ASK engine. Every denial attributed and auditable.

  • Compliance profiles

    RBI FREE-AI / HIPAA / EU AI Act — the switch at the top of every pipeline.

  • Hooks & ops

    Lifecycle hooks (CC-format), cron jobs, batch runners.

How the pieces fit together#

graph TB
    User[User / Operator] -->|REST + CLI + Dashboard| API[FastAPI API]
    API -->|permission.check| PE[Permission Engine]
    PE -->|rule sources| RBAC[RBAC] & Allowlist[Agent allowlist] & Flags[Feature flags] & HITL[HITL gates] & Policy[YAML policy]
    API --> Runner[AgentRunner]
    Runner -->|SESSION_START hook| Hooks[Hook Registry]
    Runner -->|LLM call| LLM[LLM client pool<br/>Anthropic · OpenAI]
    Runner -->|tool dispatch| Tools[Tool Executor]
    Tools -->|PRE_TOOL / POST_TOOL| Hooks
    Tools -->|logs| Denials[(permission_denials)]
    Tools -->|results| Conv[(conversation JSONL)]
    Runner -->|champion/challenger| Deploy[Model Registry]
    Cron[Cron scheduler<br/>60s tick] -->|retrain · drift · audit_pdf| Runner
    Batch[Batch runner<br/>JSONL + checkpoint] -->|pluggable processors| Tools
    Plugins[Plugin Loader] -->|skills · commands · agents · hooks · MCP| Runner
  • Every agent action flows through the permission engine before it runs.
  • Every tool call fires PRE_TOOL and POST_TOOL hooks — plugins can redact / mutate / block.
  • Every denial lands in a SQL-queryable audit table.
  • Every scheduled task (cron) is a first-class citizen, not a threading.Timer.

Reading order#