# AI··Swarms: Multi-agent orchestration

import { Steps } from "@astrojs/starlight/components"

An **AI··Swarm** in Studio is an orchestrator **AI··Task** that can call one or more worker **AI··Agents** (Flowhook
flows attached on the **Agents** tab). The orchestrator receives the problem, decides which worker to call, and uses
each Success payload to finish the job. You can mix those LLM decisions with ordinary flow steps. Screenshots on this
page use an orchestrator plus a **Mathematics Teacher** worker.

## When to use

- One AI··Task should delegate specialized work to other flows instead of holding every skill in one prompt.
- You want reusable workers (math, enrichment, ticket drafting) that several orchestrators can share.
- Prefer [Use AI··Agent](../use-ai-agent/) for attaching a single agent without the full orchestrator/worker walkthrough.
- Prefer [Call a flow](../../control-flow-execution/call-a-flow/) when the call is fixed and must not be model-chosen.

Before you begin, plan two flows in the same environment: the worker (agent) and the orchestrator. Deploy the worker
before you attach it on the orchestrator.

## Guide

### Build the worker AI··Agent

The worker is a Flowhook-based flow. The model uses the flow **name** and **description**, so keep them specific.

<ol>
<li>

**Create and name the worker.** For example **Mathematics Teacher**, with a short description of what it solves.
<div class="docs-screenshot-compact">

![Flow settings with Mathematics Teacher name and description](./assets/flow-settings-mathematics-teacher-name.png)

</div>

</li>
<li>

**Add Flowhook → work → Success.** Start with **Flowhook**, add an **AI··Task** (or other steps) for the job, end with
**Success**.
<div class="docs-screenshot-compact">

![Worker canvas: Flowhook, AI··Task, and Success](./assets/worker-canvas.png)

</div>

</li>
<li>

**Define the contract.** On **Flowhook**, set the input fields the orchestrator will pass. On **Success**, set the
output schema the orchestrator will read.
<div class="docs-screenshot-compact">

![Flowhook input fields for the worker contract](./assets/flowhook-input-fields-worker-contract.png)

</div>
<div class="docs-screenshot-compact">

![Worker AI··Task prompt for solving the delegated problem](./assets/worker-ai-task-prompt-solving-delegated.png)

</div>
<div class="docs-screenshot-compact">

![Success step output schema returned to the orchestrator](./assets/success-step-output-schema-returned-orchestrator.png)

</div>

</li>
<li>

**Deploy the worker.** Deploy it to the environment where the orchestrator will run.

</li>
</ol>
### Build the orchestrator AI··Task

The orchestrator flow holds the AI··Task that owns the overall prompt and the **Agents** list.

<ol>
<li>

**Create the orchestrator flow.** Name it for the overall job.
<div class="docs-screenshot-compact">

![Orchestrator flow title on the canvas](./assets/orchestrator-flow-title-canvas.png)

</div>

</li>
<li>

**Add an AI··Task.** Choose a tools-capable model and write a prompt that explains when to call each worker.
<div class="docs-screenshot-compact">

![Orchestrator canvas with a single AI··Task](./assets/orchestrator-canvas-single-ai-task.png)

</div>
<div class="docs-screenshot-compact">

![Orchestrator AI··Task Input with model and prompt](./assets/orchestrator-ai-task-input-model-prompt.png)

</div>

</li>
<li>

**Attach workers on Agents.** Open **Agents**, add the Mathematics Teacher (or other workers), then save.
<div class="docs-screenshot-compact">

![Orchestrator Agents tab with Mathematics Teacher attached](./assets/orchestrator-agents-tab-mathematics-teacher.png)

</div>

</li>
</ol>
### Run and inspect both flows

After a run, the orchestrator Logs show the agent call. The worker run shows what the Flowhook received and what Success
returned.

<ol>
<li>

**Run the orchestrator.** Start a run with a problem that should trigger the worker.

</li>
<li>

**Open orchestrator Logs.** Confirm the worker was invoked and inspect the request and response.
<div class="docs-screenshot-compact">

![Orchestrator Logs showing the worker agent was called](./assets/orchestrator-logs-showing-worker-agent-was.png)

</div>
<div class="docs-screenshot-compact">

![Orchestrator log detail of the query sent to the worker](./assets/orchestrator-log-detail-query-sent-worker.png)

</div>
<div class="docs-screenshot-compact">

![Orchestrator log detail of the worker response](./assets/orchestrator-log-detail-worker-response.png)

</div>

</li>
<li>

**Open the worker run.** Check Flowhook input, the worker AI··Task, and Success output.
<div class="docs-screenshot-compact">

![Worker Flowhook Logs showing the received problem](./assets/worker-flowhook-logs-showing-received-problem.png)

</div>
<div class="docs-screenshot-compact">

![Worker AI··Task Logs showing how the problem was solved](./assets/worker-ai-task-logs-showing-how.png)

</div>
<div class="docs-screenshot-compact">

![Worker Success Logs showing the payload returned to the orchestrator](./assets/worker-success-logs-showing-payload-returned.png)

</div>

</li>
</ol>
## Example

A user asks the orchestrator a word problem that needs arithmetic. The orchestrator AI··Task calls **Mathematics
Teacher** with the problem text, waits for `answer` from Success, then writes the final reply for the user. Adding a
second worker (for example a citation checker) is the same Agents attachment with an updated orchestrator prompt.

## Keep in mind

- Mindflow does not lock you to one academic swarm pattern. Orchestrator/workers is the pattern this page walks; you can
  also chain AI··Tasks, use **Call a flow**, or mix imperative steps with LLM decisions.
- Worker name and description matter as much as the prompt—keep them accurate when you rename flows.

## Related

- [Use AI··Agent](../use-ai-agent/)
- [AI··Task: A simple guide](../ai-task-a-simple-guide/)
- [Call a flow](../../control-flow-execution/call-a-flow/)