Build and operate an agent squad

​

1. What a squad is in Orbit

1. The classifier must not appear in members[] — routing the classifier’s decision back to itself recurses and bills LLM calls until the API ceiling.
2. The fallback must not equal the classifier — an unmatched intent bounces back and re-classifies the same message forever.
3. Intent labels must be unique across members — duplicates make routing ambiguous and first-match-wins varies by row order.

​

2. Create a squad via POST /agents/squads

• the classifier agent already exists (Creating agents);
• each member agent exists and carries its own prompt and providers (see below for a voice-plus-chat split);
• you hold an owner, admin, or developer role.

curl -X POST https://orbit.devotel.io/api/v1/agents/squads \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound skills squad",
    "description": "Voice triage + chat resolution for first-touch inbound",
    "classifier_agent_id": "agent_clf_triage",
    "members": [
      {
        "agent_id": "agent_voice_yours",
        "intent_labels": ["wants_voice", "callback_request", "urgent"],
        "description": "Handles any turn that needs spoken interaction or a live voice follow-up"
      },
      {
        "agent_id": "agent_chat_yours",
        "intent_labels": ["write_only", "how_to", "status_check"],
        "description": "Resolves written questions and status checks without a voice handoff"
      }
    ],
    "fallback_agent_id": "agent_human_intake",
    "active": true,
    "max_cost_per_day_cents": 5000
  }'

​

3. Assign agents and teams

​

4. Route the squad in the omnichannel queue

• Queue layer — which queue or affinity bucket the conversation enters, with SLA previewed on-queue (Omnichannel queue routing).
• Squad layer — which specialist member takes the run once the work item dispatches.

​

5. SLA and handoff targets

• agents/handoff-targets — the named resolution for every handoff verb (queue, team, human, callback, close). Point the squad’s member handoff_targets at the same named targets; escalation from a member then lands in the operator state you designed.
• concepts/agent-run-lifecycle — the run envelope: states, clock, halt conditions, and how an escalated run is counted. SLA timers and AI guardrails operate on the run, not on the squad name, so a squad that tips a run into human_review instantly joins the SLA wallboard lane.

​

6. Monitor squad utilization on the wallboard

​

7. Live monitoring

• Supervisor live monitoring of voice — listen, whisper, and barge on a voice leg the squad’s voice member escalated to a human.
• Supervisor live monitoring of digital — observe and step into a digital conversation the chat member handed off.
• Inbox SLA timers and Quality management — the run-level QA and SLA review loop for conversation outcomes.

​

Worked example — escalate LP1 → LP2 on a guardrail trip

curl -X POST https://orbit.devotel.io/api/v1/agents/squads \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LP1 to LP2 escalation squad",
    "classifier_agent_id": "agent_clf_lp_router",
    "members": [
      {
        "agent_id": "agent_lp1_inbox",
        "intent_labels": ["general_question", "account_status", "billing_lookup"],
        "description": "Confined tier: answers read-only questions on inbox and chat"
      },
      {
        "agent_id": "agent_lp2_resolve",
        "intent_labels": ["guardrail_trip", "billing_write", "refund_request", "escalation"],
        "description": "Escalation tier: finishes billing writes and handles any turn that tripped a guardrail in LP1"
      }
    ],
    "fallback_agent_id": "agent_human_intake",
    "active": true,
    "max_cost_per_day_cents": 8000
  }'

1. The LP1 member runs with its normal handoff targets (step 4–5 above) pointing at the escalation lane. When the language-quality guardrail fires on two consecutive runs, set that lane to hand off to the squad’s classifier — see agents/handoff-targets.
2. The classifier re-runs against the last LP1 message; a label such as guardrail_trip or billing_write matches the LP2 member, which serves the turn.
3. Watch it on the squad analytics rollup (step 6): handoff success rate for LP1→LP2 tells you the step-up actually fires, and containment lift versus the classifier alone tells you the escalation is doing work.
4. If LP2 cannot resolve, its own handoff target routes to agent_human_intake; the supervisor picks up from the live-monitoring surfaces in step 7.

​

Test before you deploy

curl -X POST https://orbit.devotel.io/api/v1/agents/squads/<squad_id>/test \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "I want to dispute the invoice from last month"}'

​

Reference

• agents/squads — concept and field reference
• concepts/agent-run-lifecycle — states, halt, escalation
• agents/handoff-targets — named resolution for every escalation
• Language quality — multilingual model routing drove the worked example
• Continuous production evals — keep member quality measurable