Squads

A squad (/api/squads) is a team of agents plus a pipeline of tasks and an execution strategy. Use a squad when a job is too large or nuanced for a single agent — each member has a role, tasks are assigned and ordered, and everyone shares a blackboard to pass results. To build one hands-on, see Build a squad.

The pattern: orchestrator and workers

A squad is TurfAI's take on a well-known multi-agent pattern: a central agent decomposes a goal, delegates sub-tasks to specialist workers, and synthesizes their results. The workers don't talk to each other directly — they collaborate through shared state.

Pattern framing adapted from Anthropic's "Building effective agents". In a hierarchical squad the manager_agent is that orchestrator; in a sequential squad you draw the delegation graph yourself with depends_on. Either way the shared state is the blackboard.

Configuration

A squad is created with POST /squads (body wrapped in data, like all Strapi resources). These are the fields that shape execution:

The tasks pipeline

Each task is one JSON object. The platform validates the pipeline — duplicate IDs, dependencies on unknown tasks, circular dependencies, and assignments to non-member agents are rejected before a run.

A task's per-agent iteration cap is the smaller of the agent's own max_iterations and the squad's remaining max_total_iterations budget — so a long pipeline can exhaust the budget and later tasks are skipped (see Build a squad → Troubleshooting).

The blackboard

The blackboard is shared state. Each task writes its result to a named output_key; downstream tasks read only from the keys their depends_on produced (unrelated parallel branches stay isolated). Root tasks receive the raw user inputs. Agents build on each other's work without talking directly.

The kickoff inputs are seeded onto the blackboard first under their own keys (task ID _input, agent _system), so a root task whose description references {{context}} resolves against the user's query.

Audit trail

Every write is appended to an audit trail — one entry per write, in order:

"audit_trail": [
  { "task_id": "_input",  "agent_slug": "_system",    "key": "topic",    "timestamp": 1710859200.12 },
  { "task_id": "research", "agent_slug": "researcher", "key": "research", "timestamp": 1710859231.74 },
  { "task_id": "write",    "agent_slug": "writer",     "key": "draft",    "timestamp": 1710859258.30 },
  { "task_id": "edit",     "agent_slug": "editor",     "key": "final",    "timestamp": 1710859275.91 }
]

The matching blackboard snapshot is the final value of every key:

"blackboard": {
  "topic": "AI in healthcare",
  "research": "Key findings: …",
  "draft": "A first-draft report …",
  "final": "A polished report …"
}

timestamp is epoch seconds. Together these give full traceability of who produced what, under which key, and when.

Sequential vs hierarchical

Pick sequential when you can draw the dependency graph yourself — it's deterministic, cheaper, and each step is independently auditable. Pick hierarchical when the work is exploratory and the right order depends on intermediate findings.

How each executes

• Sequential — tasks are topologically sorted, then run one at a time. Each task gets the blackboard summary of its depends_on keys, runs its agent, and writes the answer to its output_key. final_output concatenates the per-task answers.
• Hierarchical — the manager_agent is given the member list and the task descriptions, plus a delegate tool. It calls delegate(agent_slug, …) to dispatch work in whatever order it reasons is best, then synthesizes the results. task_results reports a single manager entry.

Reference

Full schema and endpoints: Squad API. Member agents: Agents. To build one hands-on, see Build a squad.