Skip to main content
Voice Agents

Agent Squads

Group specialist voice agents behind one entry point, hand a live call between them, control handoffs with a policy, dry-run the routing decision, and draft a new agent from a description.

Overview

A squad is several specialist voice agents behind one entry point. The entry agent answers, and hands the live call to a member when the caller's need matches that member's role. The member gets the whole conversation so far, introduces itself and carries on, so the caller never repeats themselves. A handoff policy bounds how far that can go, so a call cannot bounce between agents forever.

A call runs as a squad when you bind the squad to a phone number, pass squad_id when you create a voice session, or set squad_id on an agent. See Live handoff for what happens on the call.

Two extras sit alongside the roster:

  • POST /{squad_id}/simulate-handoff — a pure dry run that shows which member would be picked and why.
  • POST /author/draft — describe an agent in prose and get a complete configuration proposal back. This one costs credits.

Authentication

Authorization: Bearer cm_your_api_key
OperationScope
List/get squads, list members, simulate a handoffsquads:read
Create/update/delete squads and members, draft an agentsquads:write
Bind or unbind a phone numbersquads:write and telephony:write

Limits

ThingLimit
Members per squad12. Past that, use a call flow
Handoffs per call0..5, default 3
Role name64 characters
Member description2,000 characters

Squads

{
  "id": "sq10…",
  "tenant_id": "a0b1…",
  "name": "Support desk",
  "description": "Front line plus billing and technical specialists.",
  "entry_bot_id": "b1f2…",
  "handoff_policy": {
    "max_handoffs": 3,
    "allow_return_to_previous": false,
    "min_score": 1,
    "fallback_role": "generalist"
  },
  "is_active": true,
  "created_at": "2026-08-11T09:00:00Z",
  "updated_at": "2026-08-11T09:00:00Z",
  "members": []
}

Handoff policy

FieldTypeDefaultConstraints
max_handoffsinteger30 <= n <= 5. 0 disables handoffs entirely
allow_return_to_previousbooleanfalseLeaving this false is what stops two agents ping-ponging a caller
min_scoreinteger11 <= n <= 20. The match strength a member must reach to be handed to
fallback_rolestring | nullnullRole to use when nothing scores high enough

Unknown keys inside the policy are rejected with 422.

GET/api/v1/voice/squads

Newest first. Filter by is_active. limit 1..200 (default 50), offset 0..100000.

POST/api/v1/voice/squads

FieldTypeRequiredConstraints
namestringYes1–255 characters, unique per tenant
descriptionstringNoAt most 500 characters
entry_bot_idUUIDYesThe agent that answers the call
entry_rolestringNo1–64 characters, default entry
entry_descriptionstringNoAt most 2,000 characters
handoff_policyobjectNoOmit for the defaults above
is_activebooleanNoDefault true

Creating a squad automatically enrols the entry agent as the first member at position: 0 — you do not add it yourself.

Returns 201 with the squad and its roster.

GETPATCHDELETE/api/v1/voice/squads/{squad_id}

PATCH takes name, description, entry_bot_id, handoff_policy (an explicit null clears it back to defaults) and is_active.

entry_bot_id must point at an agent already in the squad — 422 entry_bot_id must be a bot that is already a member of this squad. Add the member first, then promote it.

DELETE returns 204 and cascades the roster.


Members

{
  "id": "mb20…",
  "tenant_id": "a0b1…",
  "squad_id": "sq10…",
  "bot_id": "b7c8…",
  "role": "billing",
  "description": "Handles invoices, refunds and payment failures.",
  "position": 1,
  "created_at": "2026-08-11T09:02:00Z"
}

role and description are what the routing engine matches a caller's utterance against — write the description as the things this agent handles, in the caller's words.

GET/api/v1/voice/squads/{squad_id}/members

Ordered by position, then oldest first. No pagination — the 12-member cap bounds it.

POST/api/v1/voice/squads/{squad_id}/members

FieldTypeRequiredConstraints
bot_idUUIDYesMust be your agent, not already in this squad
rolestringYes1–64 characters, not blank
descriptionstringNoAt most 2,000 characters
positionintegerNo0 <= position <= 1000, default 0

422 A squad holds at most 12 agents. Past that, use a call flow. · 409 That agent is already in this squad.

Members share one live call, so every member must run the same kind of voice pipeline as the squad's entry agent (all speech-to-text + language model + text-to-speech, or all speech-to-speech models such as gpt-realtime) and be on the same voice tier, because a call is billed at one tier. An agent on a managed voice-agent model (deepgram-voice-*, or the tier built on one) cannot take over a call from another agent. Each case is a 422 with the reason.

PATCHDELETE/api/v1/voice/squads/members/{member_id}

PATCH takes role, description (explicit null clears it) and position. bot_id is not editable — remove the member and add the other agent.

Removing the entry agent returns 409 This agent answers the call for the squad. Point entry_bot_id at another member before removing it.


Live handoff on a call

While a call runs as a squad, the agent answering it can hand the caller to another member. It sees every other member's role and description and picks one when the caller's need is clearly that member's job. Then:

  1. The handoff is checked against the squad's handoff policy: the per-call cap, no handing straight back to the member that just handed over (unless allow_return_to_previous), no handing to itself, and only roles on the roster. The agent can propose a member; it cannot get around these rules.
  2. The new member takes the call in the same session: same caller, same recording, same transcript. It receives the conversation so far, introduces itself in one sentence and continues. It does not repeat the greeting or the recording notice.
  3. The handoff is recorded on the session (metadata.squad_handoffs on GET /v1/voice/sessions/{id}: from and to agent, roles, reason, time), the session's bot_id moves to the new member, and a call.handoff webhook is sent.

From the handoff on, the new member's prompt, voice, language, model, tools, fallback transfer and moderation settings apply, and its usage is billed at its own model rates (or the squad's tier). Settings fixed when the call started stay with the call: turn-taking, the pronunciation dictionary, the moderation blocklist, call recording and its notice, and the AI disclosure (spoken once, at the start of the call).

An agent that is inactive is never handed a call. An agent in zero data retention mode can only hand a call to another agent in that mode (the handoff is refused with data_retention otherwise), so content from the first part of the call is never stored by the next agent. If a handoff cannot be completed, the agent keeps the caller and carries on.


Answering a phone number

POST/api/v1/voice/squads/{squad_id}/numbers/{number_id}

Answer inbound calls on one of your numbers with this squad. The squad's entry agent answers, with the number's own call settings (greeting, voice and so on) applied as they would be for the number's agent. Needs squads:write and telephony:write.

curl -X POST https://api.callmissed.com/api/v1/voice/squads/sq10…/numbers/pn40… \
  -H "Authorization: Bearer cm_your_api_key"
{ "status": "bound", "squad_id": "sq10…", "number_id": "pn40…" }

A number answers with one squad; binding another squad replaces it. A call flow, call menu or call queue on the same number answers first, and the squad does not apply to those calls. An inactive squad, or one whose entry agent is inactive, leaves the number answering with its own agent.

DELETE/api/v1/voice/squads/{squad_id}/numbers/{number_id}

Stop answering the number with this squad. Returns {"status": "unbound", …}. Idempotent: a number bound to a different squad, or to none, is left as it is.

404 Squad not found · 404 Phone number not found (not one of your numbers).


Web and API sessions

Pass squad_id to POST /v1/voice/sessions. The squad's entry agent answers, or bot_id when you name another active member. The answering agent uses its own prompt, greeting and voice; any field you send in the request still wins. 404 for an unknown or inactive squad, 422 for a bot_id that is not an active member.


An agent's own squad

Set squad_id in an agent's configuration and the agent hands calls within that squad on any call it answers or places, as long as it is a member. A value that is not a squad id is reported by config validation; remove it with { "unset": ["squad_id"] }.

curl -X PATCH https://api.callmissed.com/api/v1/bots/{bot_id}/config \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "values": { "squad_id": "sq10…" } }'

Simulating a handoff

POST/api/v1/voice/squads/{squad_id}/simulate-handoff

Requires squads:read. Pure and read-only: no model call, no credits, nothing written.

FieldTypeRequiredConstraints
utterancestringYes1–2,000 characters
handoffs_usedintegerNo0 <= n <= 100, default 0
current_member_idUUIDNoWho is handling the call now
previous_member_idUUIDNoWho handled it before — used for the ping-pong check
curl -X POST https://api.callmissed.com/api/v1/voice/squads/sq10…/simulate-handoff \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "utterance": "my card was charged twice", "handoffs_used": 1, "current_member_id": "mb01…" }'
{
  "squad_id": "sq10…",
  "handoff": true,
  "target_member_id": "mb20…",
  "target_bot_id": "b7c8…",
  "target_role": "billing",
  "reason": "matched billing on 'charged'",
  "blocked_by": null,
  "score": 3,
  "handoffs_used": 1,
  "max_handoffs": 3,
  "scores": [
    { "member_id": "mb20…", "role": "billing", "score": 3, "eligible": true },
    { "member_id": "mb30…", "role": "technical", "score": 0, "eligible": true }
  ]
}

scores shows every member's match strength, so a wrong route is debuggable: if the right agent scored 0, its description is missing the words callers actually use.

Why a handoff was blocked

blocked_byMeaning
no_membersThe squad has no one to hand to
max_handoffsThe policy's handoff budget is spent
ping_pongThe target is the previous member and returns are disallowed
already_currentThe best match is already handling the call
no_matchNothing reached min_score
unknown_roleA routing model named a role that is not on the roster. Only produced by model-based routing on a live call; this keyword dry run never returns it

Drafting an agent

POST/api/v1/voice/squads/author/draft

Requires squads:write. Charges credits. It creates nothing — you get a proposal to review and then submit yourself via the bots API.

FieldTypeRequiredConstraints
descriptionstringYes20–4,000 characters, not blank
bot_typestringNoinbound_call (default), outbound_call, ivr, whatsapp or whatsapp_voice
curl -X POST https://api.callmissed.com/api/v1/voice/squads/author/draft \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "An agent for a Pune dental clinic that books, moves and cancels appointments in Hindi and English, and escalates anything about pain to a human.",
    "bot_type": "inbound_call"
  }'
{
  "draft": {
    "name": "Clinic Reception",
    "bot_type": "inbound_call",
    "system_prompt": "You are the receptionist for a dental clinic in Pune…",
    "objective": "Book, reschedule or cancel appointments; escalate pain reports.",
    "response_guidelines": "Keep replies under two sentences…",
    "conversation_script": "",
    "first_message": "Namaste, thanks for calling. How can I help?",
    "tools": ["calcom_list_slots", "calcom_book", "escalate_to_human"],
    "voice_model": "…",
    "tts_model": "…",
    "stt_model": "…",
    "voice": "shubh",
    "language": "hi-IN",
    "analysis_variables": [
      { "name": "appointment_booked", "type": "boolean", "use_as_goal": true, "description": "True if an appointment was booked or moved to a new slot on this call." }
    ]
  },
  "dropped_tools": ["send_invoice"],
  "model": "…"
}

dropped_tools lists tools the draft asked for that are not in your tool registry — they were removed so the configuration is valid on submission. Check this list: a dropped tool usually means the capability you described is not wired up yet.

At most 12 tools are proposed, de-duplicated and validated against the registry.

analysis_variables is the set of result fields for the job the description matches (appointment booking, lead qualification, payment reminders, order confirmation, support, feedback and so on): what the agent records after each call. Save it as config.analysis_variables when you create the agent and each field becomes a column in the call log and in exports. It is an empty list when the description matches none of the built-in jobs.

StatusDetailNote
402Not enough credits to draft an agent. Top up to continue.Checked before any model runs — costs nothing
402Monthly budget cap reachedYour account's monthly budget cap is spent. Also checked before any model runs
422Could not draft an agent: …The model returned an unusable draft. This attempt is still billed — the work was done
503The agent drafting service is unavailable.Retry

Cost appears in usage logs as service: "llm".

Errors

StatusWhen
402Credit balance exhausted, or the monthly budget cap reached, before drafting
403Key is missing squads:read / squads:write
404Squad, member, agent or phone number not in your tenant
409Duplicate squad name, agent already a member, or removing the entry agent
422Over 12 members, a blank name/role, an unknown key in handoff_policy, an entry_bot_id that is not a member, or a member on a different voice pipeline or tier

On this page