Squads & Handoffs

Overview

Sulus provides a powerful multi-agent system called Squads that allows you to transfer calls between specialized assistants.

A Squad is a collection of assistants that work together, where each assistant can hand off a call to another based on the conversation context. Squads enable you to build specialized workflows like routing maintenance vs. leasing inquiries, clinic triage, or customer support escalation.

Define your squad members, each with their own system prompt and tools:

{
  "members": [
    {
      "assistant": {
        "name": "Router",
        "model": {
          "provider": "openai",
          "model": "gpt-4o",
          "messages": [{"role": "system", "content": "Classify inquiries and transfer accordingly."}]
        },
        "firstMessage": "Thanks for calling. How can I help?",
        "firstMessageMode": "assistant-speaks-first"
      }
    },
    {
      "assistant": {
        "name": "Specialist",
        "model": {
          "provider": "openai",
          "model": "gpt-4o",
          "messages": [{"role": "system", "content": "Domain specialist assistant."}]
        }
      }
    }
  ]
}

Transfers between assistants are powered by the handoff tool. You can configure it in several ways:

By assistant ID:

{
  "tools": [
    {
      "type": "handoff",
      "destinations": [
        {
          "type": "assistant",
          "assistantId": "03e11cfe-4528-4243-a43d-6aded66ab7ba",
          "description": "customer wants to speak with technical support",
          "contextEngineeringPlan": { "type": "all" }
        }
      ]
    }
  ]
}

By assistant name (within a squad):

{
  "tools": [
    {
      "type": "handoff",
      "destinations": [
        {
          "type": "assistant",
          "assistantName": "TechnicalSupportAgent",
          "description": "customer needs technical assistance",
          "contextEngineeringPlan": { "type": "all" }
        }
      ]
    }
  ]
}

You can configure multiple transfer destinations. The recommended pattern depends on your LLM provider:

For runtime routing, use a dynamic destination type that calls a webhook to determine where to send the call:

{
  "tools": [
    {
      "type": "handoff",
      "destinations": [
        {
          "type": "dynamic",
          "server": {
            "url": "https://api.example.com/determine-handoff-destination"
          }
        }
      ]
    }
  ]
}

Your server responds with the destination assistant, or an error to cancel the handoff.

Control what conversation history is passed to the next assistant:

import { CoreSystemClient } from "@core-system/server-sdk";
const client = new CoreSystemClient({ token: process.env.CORE_SYSTEM_API_KEY! });

await client.calls.create({
  transport: { type: "web" },
  squad: {
    members: [
      {
        assistant: {
          name: "Router",
          model: { provider: "openai", model: "gpt-4o", messages: [{ role: "system", content: "Route inquiries to the right specialist." }] },
          firstMessage: "Thanks for calling. How can I help?",
          firstMessageMode: "assistant-speaks-first",
        },
      },
      {
        assistant: {
          name: "Specialist",
          model: { provider: "openai", model: "gpt-4o", messages: [{ role: "system", content: "Domain specialist." }] },
        },
      },
    ],
  },
});

Add this to each assistant's system prompt for smooth handoffs:

# System context
You are part of a multi-agent system. Handoffs are achieved by calling a handoff 
function, generally named handoff_to_<agent_name>. Do not mention or draw 
attention to these handoffs in your conversation with the user.

In summary, Sulus Squads let you compose specialized assistants that transfer calls seamlessly using the handoff tool. You can route statically by assistant ID/name, dynamically via webhook, or even hand off to an entire nested squad, all with fine-grained control over what conversation context is passed along.