Multi-Agent Coordination

Build agent swarms with real-time state sync, resource locking, and task handoffs. Coordinate multiple AI agents working on complex, interdependent tasks.

Plan Requirements

Multi-Agent Coordination features vary by plan. Task queues require Pro+, real-time events require Team+.

Overview

Multi-Agent Coordination enables multiple AI agents to work together on complex tasks. This includes:

Swarms — Groups of agents working toward a shared goal
Resource Locking — Prevent conflicts when modifying shared resources
Shared State — Synchronized key-value store across agents
Task Queues — Distributed work queues with claim/complete semantics
Real-time Events — Broadcast messages to other agents

Swarms

A swarm is a coordinated group of agents working together. Each swarm has a unique ID, shared state, and can coordinate via resource locks and task queues.

Creating a Swarm

rlm_swarm_create({

  name: "refactor-auth",

  goal: "Refactor authentication system to use JWT",

  maxAgents: 5

})

// Response:

  "swarmId": "swarm_abc123",

  "joinCode": "XKCD-1234"

Joining a Swarm

Other agents can join using the swarm ID or join code:

rlm_swarm_join({

  swarmId: "swarm_abc123",

  role: "worker"  // Optional: "coordinator", "worker", or "observer"

})

Swarm Roles

Role	Description	Typical Use
`coordinator`	Plans and assigns tasks	Senior agent that decomposes work
`worker`	Executes assigned tasks	Agents that write code, review, or test
`observer`	Read-only access	Monitoring, logging

Resource Locking

Prevent multiple agents from modifying the same resource simultaneously using claims:

Claiming a Resource

// Agent wants to modify a file

const claim = await rlm_claim({

  resource: "file:src/auth/login.ts",

  swarmId: "swarm_abc123",

  ttl: 300  // 5 minute lock

})

if (claim.acquired) {

  // Safe to modify the file

  // ... do work ...

  await rlm_release({ claimId: claim.claimId })

} else {

  // Another agent has this resource

  console.log("Held by:", claim.heldBy)

Claim Parameters

Parameter	Type	Description
`resource`	string	Resource identifier (e.g., "file:path", "db:table")
`swarmId`	string	Swarm context for the lock
`ttl`	number	Lock timeout in seconds (max 3600)
`wait`	boolean	Wait for lock vs immediate fail
`waitTimeout`	number	Max wait time in seconds

Shared State

Agents in a swarm can read and write shared key-value state:

// Set state

rlm_state_set({

  swarmId: "swarm_abc123",

  key: "current_phase",

  value: "implementation"

})

// Get state

const state = await rlm_state_get({

  swarmId: "swarm_abc123",

  key: "current_phase"

})

// state.value === "implementation"

Atomic Updates

For counters and other values that need atomic updates:

// Increment a counter atomically

rlm_state_set({

  swarmId: "swarm_abc123",

  key: "files_processed",

  operation: "increment",

  delta: 1

})

Task Queues

Distribute work across agents using task queues. Tasks are claimed, processed, and completed:

Creating Tasks

// Coordinator creates tasks

rlm_task_create({

  swarmId: "swarm_abc123",

  type: "implement",

  title: "Add JWT token generation",

  description: "Implement JWT signing in src/auth/jwt.ts",

  priority: "high",

  dependencies: []  // IDs of tasks that must complete first

})

Claiming and Completing Tasks

// Worker claims next available task

const task = await rlm_task_claim({

  swarmId: "swarm_abc123",

  types: ["implement", "fix"]  // Task types this agent handles

})

if (task) {

  // Do the work...

  // Mark complete with result

  await rlm_task_complete({

    taskId: task.id,

    status: "completed",

    result: { filesModified: ["src/auth/jwt.ts"] }

})

Task States

pending

Task created, waiting to be claimed

claimed

Agent is working on the task

completed

Task finished successfully

failed

Task failed (can be retried)

Real-time Events (Team+)

Broadcast messages to other agents in the swarm for real-time coordination:

// Broadcast event to swarm

rlm_broadcast({

  swarmId: "swarm_abc123",

  event: "phase_complete",

  data: {

    phase: "planning",

    tasksCreated: 12

})

Event Types

Event	Description	Use Case
`task_available`	New task added to queue	Wake idle workers
`phase_complete`	Major milestone reached	Coordinate phase transitions
`resource_released`	Lock released	Allow waiting agents to proceed
`error`	Critical error occurred	Alert other agents
`custom`	Application-specific	Any coordination need

Example: Coordinated Refactoring

Here's a complete example of multiple agents working together to refactor a codebase:

Coordinator Agent

// Create swarm and plan work

const swarm = await rlm_swarm_create({

  name: "auth-refactor",

  goal: "Migrate from sessions to JWT"

})

// Create tasks for workers

await rlm_task_create({

  swarmId: swarm.swarmId,

  type: "implement",

  title: "Create JWT utilities",

  description: "Add sign/verify functions"

})

// ... more tasks ...

await rlm_broadcast({

  swarmId: swarm.swarmId,

  event: "tasks_ready",

  data: { count: 5 }

})

Worker Agent

// Join swarm and work

await rlm_swarm_join({

  swarmId: "swarm_abc123",

  role: "implementer"

})

while (true) {

  const task = await rlm_task_claim({

    swarmId: "swarm_abc123",

    types: ["implement"]

})

  if (!task) break  // No more tasks

  // Claim resource lock before editing

  const lock = await rlm_claim({

    resource: `file:${task.targetFile}`,

    swarmId: "swarm_abc123"

})

  // Do the implementation...

  await rlm_release({ claimId: lock.claimId })

  await rlm_task_complete({ taskId: task.id })

Plan Limits

Feature	Starter	Pro	Team	Enterprise
Swarms	1	5	20	Unlimited
Agents/Swarm	2	5	15	50
Resource Locks	10	100	500	Unlimited
Task Queue	—	Yes	Yes	Yes
Real-time Events	—	—	Yes	Yes

Best Practices

Start simple — Use shared state before adding task queues
Always release locks — Use try/finally to ensure release
Set appropriate TTLs — Prevent deadlocks from crashed agents
Use task dependencies — Ensure correct execution order
Monitor swarm state — Check swarm status via the dashboard or API
Handle claim failures gracefully — Retry or work on other tasks

Next Steps

Agents Overview

Learn about Snipara Agents and how to get started.

Agent Memory

Add persistent memory to individual agents.

Group Memory

Share knowledge across agents and teammates.

Go to Dashboard

Start building agent swarms now.