Orchestration

SwarmClaw uses LangGraph for multi-agent orchestration. An orchestrator agent routes tasks to specialized sub-agents automatically.

How It Works

  1. You send a message to an orchestrator agent
  2. The orchestrator analyzes the request and decides which sub-agent(s) to invoke
  3. Sub-agents execute their tasks and return results
  4. The orchestrator synthesizes and responds

For long-lived objectives, orchestrators can also use platform tools (manage_tasks, manage_schedules, manage_agents, etc.) to create ongoing execution plans rather than stopping at a one-shot response.

Agent-to-Agent Delegation

Any agent (not just orchestrators) with the orchestrator capability toggle enabled can delegate tasks to other agents. This is separate from the LangGraph multi-agent orchestration above — it uses the task board as the coordination layer. Enable it via the Orchestrator toggle in the tools popover or agent editor. See Tools — Orchestrator Capability.

Setting Up an Orchestrator

1. Create Sub-Agents

Create the specialized agents first. For example:

  • Code Writer — writes code (provider: Anthropic, model: claude-sonnet)
  • Code Reviewer — reviews code for bugs (provider: OpenAI, model: gpt-4o)
  • Doc Writer — writes documentation (provider: Ollama, model: llama3)

2. Create the Orchestrator

Create a new agent and toggle Is Orchestrator on. Then:

  • Select sub-agents from the multi-select
  • Set a system prompt describing when to route to each agent
  • Choose a provider (not Claude CLI — orchestrators need LangGraph)

3. Start a Chat

Create a new chat with the orchestrator agent. Messages are automatically routed to the appropriate sub-agent based on content.

Provider Requirements

Orchestrators can use any non-CLI provider from your Providers list (Anthropic, OpenAI, Ollama, OpenAI-compatible providers, and custom providers).
CLI providers (claude-cli, codex-cli, opencode-cli) are not used for LangGraph orchestration routing.

Orchestrator Engine

In Settings, you can configure a separate provider/model for the orchestration routing layer. This is the LLM that decides which sub-agent handles a request. It doesn't need to be the same provider as the sub-agents.

Loop Behavior

In Settings → Runtime & Loop Controls, you can choose:

  • Bounded mode for fixed step limits
  • Ongoing mode for long-running autonomous loops, guarded by a configurable max-step cap and optional max-runtime budget

This setting applies to both normal tool-using agent loops and orchestrator routing loops.

Heartbeat (Ongoing Chats)

In Settings → Heartbeat, you can configure:

  • Heartbeat Interval (Seconds) — how often ongoing chats are pinged
  • Heartbeat Prompt — internal message text used for heartbeat checks

On a heartbeat ping, the assistant should return:

  • HEARTBEAT_OK when there is no important status update
  • A concise progress update + next step when active work is underway

In chat UI, heartbeat entries render as compact expandable cards. Consecutive heartbeat streaks are visually collapsed to the latest heartbeat so long-running chats stay readable.

This makes long-running orchestration feel more alive and observable during autonomous runs without flooding the chat transcript.

Checkpointing & Resumption

Orchestrator runs are checkpointed via LangGraph's persistence layer. This enables:

  • Task approval workflow — When capability policy is set to strict, the orchestrator pauses before tool execution and waits for human approval. See Tasks — Approval Workflow.
  • Crash recovery — If the server restarts mid-orchestration, the run can resume from the last checkpoint.

Checkpoints are stored in data/langgraph-checkpoints.db (SQLite).

Checkpoint Timeline

The chat detail panel includes a Checkpoint Timeline that shows the full checkpoint history for an orchestrator run. Each checkpoint displays:

  • Timestamp and checkpoint ID
  • Metadata (step number, source)
  • Message count at that point

Click Restore on any checkpoint to rewind the conversation to that point in time. This deletes all checkpoints after the selected one and truncates messages to match, effectively implementing time-travel debugging for orchestrator runs.

API:

  • GET /api/chats/[id]/checkpoints — List checkpoint history
  • POST /api/chats/[id]/restore with { "checkpointId": "..." } — Restore to a checkpoint

Delegation Cards

When an orchestrator delegates to a sub-agent, the chat thread displays a rich delegation card showing:

  • The agent name (clickable — navigates to that agent's chat thread)
  • The task that was delegated
  • A preview of the result

This replaces the old plain-text delegation messages with interactive, navigable cards.

Limitations

  • Sub-agents execute sequentially (no parallel fan-out yet)
  • Orchestrators cannot be nested (an orchestrator can't have another orchestrator as a sub-agent)
  • Claude CLI agents can be sub-agents but not orchestrators