Advanced
Agent Swarms
Coordinate multi-agent systems at scale
A swarm is a coordinated group of agents working toward one goal — planning, delegating, and merging results. Use swarms when a task is too big or too varied for a single agent.
Topologies
| Topology | Shape | Good for |
|---|---|---|
| Orchestrator | One planner delegates to workers | Decompose‑then‑solve tasks |
| Pipeline | Agents in sequence, output → input | Multi‑stage processing |
| Debate | Agents critique each other, then converge | Higher‑quality reasoning |
| Map‑reduce | Fan out over items, aggregate | Large batches |
Define a swarm
{
"name": "Research & Draft",
"topology": "orchestrator",
"agents": [
{ "id": "agent_planner", "role": "orchestrator" },
{ "id": "agent_researcher", "role": "worker", "tools": ["web"] },
{ "id": "agent_writer", "role": "worker" }
],
"goal": "Produce a sourced 1000-word brief on {topic}",
"limits": { "max_steps": 40, "budget_credits": 3000 }
}
curl -X POST https://api.theaimart.co/api/v1/swarms \
-H "Authorization: Bearer $THEAIMART_API_KEY" \
-H "Content-Type: application/json" \
-d @swarm.json
Guardrails
Swarms can loop or fan out unexpectedly. Always cap max_steps and budget_credits, and set per‑agent tool permissions to the minimum. A runaway swarm is the fastest way to burn credits.
- •Termination: define a clear done condition; don't rely on step limits alone.
- •Isolation: each agent only gets the tools its role requires.
- •Observability: the run graph shows every message, delegation, and cost node.
Swarm vs. Workforce
- •Swarm — many agents, one coordinated task, runs to completion.
- •Workforce — persistent workers doing recurring roles on a schedule.
Combine them: a scheduled Workforce worker can launch a Swarm for each batch of incoming work.