​

Agent squads

​

What a squad is

• Classifier agent — the front door. On every inbound turn Orbit asks it a single, constrained question: “Which of these intent labels best fits this message?” The classifier answers with exactly one label, and that label decides where the turn goes.
• Member agents (2–6) — the specialists. Each member is declared with an agent ID, one or more intent labels (up to 10), and a short description that tells the classifier what kinds of messages the label covers.
• Fallback agent (optional) — receives turns the classifier maps to no member, and turns where the classifier itself is unreachable (for example a provider timeout).
• Daily cost cap (optional) — max_cost_per_day_cents bounds the squad’s LLM spend per UTC day. When the cap is reached, routing stops with a 429 instead of firing further model calls.

​

When to use a squad

• Handoff targets (the non-squad equivalent): one router agent converses with the user and hands off with a tool call. Good when the router should have a personality, answer simple questions itself, or hand off mid-conversation. See Agent handoff targets.
• Squad (this page): a classifier labels the message, usually on its first turn, and a specialist owns the conversation from there. Good when you want strict multi-persona separation — sales vs support vs returns — where each specialist carries its own model, knowledge bases, and guardrails, and where membership lives in one config object instead of spread across every peer’s allowlist.

​

Smart routing — build the classifier

You are a message router. Classify the user's message into exactly one of
the squad's labels. Respond with only the label, nothing else.

​

Define the members

curl -X POST https://api.orbit.devotel.io/api/v1/agents/squads \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Router",
    "description": "Routes inbound support chats to the right specialist",
    "classifier_agent_id": "agent_classifier01",
    "members": [
      {
        "agent_id": "agent_sales01",
        "intent_labels": ["sales"],
        "description": "Pricing, quotes, and product questions"
      },
      {
        "agent_id": "agent_support01",
        "intent_labels": ["support"],
        "description": "Account issues, bugs, and how-to questions"
      },
      {
        "agent_id": "agent_returns01",
        "intent_labels": ["returns", "refunds"],
        "description": "Return requests and refund status"
      }
    ],
    "fallback_agent_id": "agent_general01",
    "max_cost_per_day_cents": 500
  }'

​

Fallback and cost cap semantics

• When the classifier returns “none” or any uncertainty signal, the turn goes to the fallback.
• When the classifier emits a label no member claims (normalisation aside), the turn goes to the fallback.
• When the classifier call itself fails (provider timeout, malformed response), the turn goes to the fallback rather than erroring the conversation.

​

Visualise the canvas

curl -X POST https://api.orbit.devotel.io/api/v1/agents/squads/squad_abc123/test \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "message": "My order never arrived, I want a refund" }'

​

End-to-end example

1. Create the four agents: a classifier, a sales specialist, a support specialist, and a general fallback. Deploy the classifier to your inbound channel — the classifier is the squad’s entry point.
2. Create the squad with sales → agent_sales01, support → agent_support01, fallback → agent_general01.
3. Test it with a few realistic messages (POST /:id/test) and adjust member descriptions until every sample lands on the intended label.
4. An inbound “I want to add three more seats” classifies as sales → the sales specialist takes over. “The export feature throws a 500” classifies as support → the support specialist takes over. “Hey, what do you folks do?” doesn’t match → the fallback generalist handles it.
5. Watch the analytics panel for members with high handoff drop-off; tighten their label descriptions or add a second label to close the gap.

​

See also

• Agent handoff targets — the router-as-agent alternative for mid-conversation hand-off with an allowlist.
• Cost controls — per-agent daily spend limits that sit beneath the squad cap.
• Model selection — pick a fast, cheap model for the classifier; heavier models for the specialists.
• Creating agents — build the classifier and specialist agents the squad references.
• Agents API reference — full request/response schemas for the squad endpoints.