Swarm
Agents decide at runtime who handles the next step. Execution begins at an entry point and flows through handoffs until a final answer is produced. All agents run inside the same app on the same device.
When to Use Swarm
- The routing logic depends on what the user actually asked
- You cannot predict which specialist is needed ahead of time
- Your app has a natural language assistant that covers several domains (calendar, notes, tasks, and so on)
- You want the model itself to decide which on-device specialist handles each request
How It Works
Each agent in the swarm is a SwarmMember with an ID and a description. The swarm exposes all other members' descriptions to the active agent via a hidden handoff tool. When an agent decides it has finished its part, it hands off to another member by name.
Basic Example
An in-app personal assistant on iOS or macOS. The user can ask anything in natural language. A coordinator agent reads the intent and routes to the right on-device specialist: calendar (EventKit), notes (local notes store), or tasks (Reminders).
import StrandsAgents
let coordinatorAgent = Agent(
model: provider,
systemPrompt: """
You are a personal assistant coordinator. Read the user's request and hand off to the right specialist:
- "calendar-agent": scheduling, events, reminders, availability
- "notes-agent": creating or finding notes, saving information
- "tasks-agent": to-do items, task lists, Reminders
Hand off immediately. Do not try to answer yourself.
"""
)
let calendarAgent = Agent(
model: provider,
tools: [readCalendar, createEvent, checkAvailability],
systemPrompt: "You manage the user's calendar using EventKit. Create events, check availability, and answer scheduling questions."
)
let notesAgent = Agent(
model: provider,
tools: [searchNotes, createNote, appendToNote],
systemPrompt: "You manage the user's notes. Search existing notes and create new ones on request."
)
let tasksAgent = Agent(
model: provider,
tools: [listReminders, createReminder, completeReminder],
systemPrompt: "You manage the user's task lists using the Reminders store. Add, complete, and list tasks."
)
let swarm = SwarmOrchestrator(
members: [
SwarmMember(id: "coordinator", description: "Routes requests to the right on-device specialist", agent: coordinatorAgent),
SwarmMember(id: "calendar-agent", description: "Manages calendar events and availability", agent: calendarAgent),
SwarmMember(id: "notes-agent", description: "Creates and searches notes", agent: notesAgent),
SwarmMember(id: "tasks-agent", description: "Manages Reminders and to-do lists", agent: tasksAgent),
],
entryPoint: "coordinator"
)
let result = try await swarm.run("Schedule a team lunch for Friday at noon")
print(result.output)Handoffs
A handoff transfers execution to another agent, carrying the full conversation context. The receiving agent sees everything that happened before: all previous messages, tool results, and handoff notes.
Agents must be explicitly instructed in their systemPrompt to hand off and to whom. The model will not hand off unless told it should. Keep the list of available agents and their roles in the system prompt.
Entry Point
The entryPoint parameter specifies which agent receives the user's initial message. Usually this is a coordinator or router agent that assesses the task and delegates, but it can be any member:
// Start directly at a specialist for focused tasks
let swarm = SwarmOrchestrator(
members: [
SwarmMember(id: "calendar-agent", description: "Manages calendar events", agent: calendarAgent),
SwarmMember(id: "tasks-agent", description: "Manages Reminders", agent: tasksAgent),
],
entryPoint: "calendar-agent" // skip coordinator; always start with calendar
)Real-World Example: Fitness App Assistant
A fitness app with a natural language assistant. The user asks about workouts, nutrition, or recovery. A triage agent reads the intent and routes to the right specialist. Each specialist has its own tools and on-device data.
let triageAgent = Agent(
model: provider,
systemPrompt: """
You are a fitness assistant coordinator. Read the user's request and hand off:
- Exercise and training → "workout-agent"
- Food, calories, macros → "nutrition-agent"
- Rest, soreness, sleep → "recovery-agent"
Do not answer directly. Triage and hand off.
"""
)
let workoutAgent = Agent(
model: provider,
tools: [readWorkoutHistory, suggestExercise, logWorkout],
systemPrompt: "You are a personal trainer. Review the user's workout history and suggest or log training sessions."
)
let nutritionAgent = Agent(
model: provider,
tools: [readFoodLog, searchFoodDatabase, logMeal],
systemPrompt: "You are a nutrition coach. Help the user track calories and macros and suggest meals aligned with their goals."
)
let recoveryAgent = Agent(
model: provider,
tools: [readSleepData, readHeartRateVariability, suggestRecovery],
systemPrompt: "You are a recovery specialist. Review the user's sleep and HRV data and suggest rest or active recovery activities."
)
let swarm = SwarmOrchestrator(
members: [
SwarmMember(id: "triage", description: "Routes fitness questions to the right specialist", agent: triageAgent),
SwarmMember(id: "workout-agent", description: "Plans and logs workouts", agent: workoutAgent),
SwarmMember(id: "nutrition-agent", description: "Tracks food and recommends meals", agent: nutritionAgent),
SwarmMember(id: "recovery-agent", description: "Advises on rest and recovery", agent: recoveryAgent),
],
entryPoint: "triage"
)
let result = try await swarm.run("I feel sore today. Should I work out or rest?")
print(result.output)Swarm vs. Graph
| Graph | Swarm | |
|---|---|---|
| Routing | Declared by you | Decided by the model |
| Execution order | Deterministic | Dynamic |
| Parallelism | Built-in (independent nodes) | Not built-in |
| Best for | Known, structured pipelines | Open-ended tasks |
| Predictability | High | Lower |