Squads and Multi-Agent

In SquadOS, a squad is not an object, a page, or a special agent type. It is an architecture pattern: you create regular agents, specialize each one, and connect their exits with the Transfer Conversation tool.

The most common design has a triage agent, specialists, and human support when needed. Each agent keeps its own prompt, model, tools, knowledge bases, and settings.

When to split agents

Keep one agent when the scope is coherent, the prompt remains clear, and nearly every conversation uses the same tools and knowledge.

Split the work among agents when there is at least one real operational boundary, such as:

• areas with different responsibilities, such as Sales, Support, and Finance;
• tools or knowledge bases that only one specialist should use;
• substantially different models, limits, or instructions;
• mandatory human handoff for specific cases or hours.

Do not create an agent for every intent. More transfers increase cost, failure points, and the risk of context loss. The split should follow who decides and who executes.

Design the topology first

List each agent and record:

Role	Receives from	Resolves	May transfer to
Triage	inbox	initial classification	specialists or human
Specialist	triage	one defined domain	human or an exceptional destination
Human	agents	exceptions and reserved decisions	queue or assignee

Prefer a simple flow with unambiguous exit criteria. SquadOS has no visual graph editor and does not validate persistent cycles. An agent that just received a conversation cannot pass it to another agent in the same turn, but the full tool returns on the customer’s next message; therefore A → B and B → A can still oscillate over the conversation when reasons are vague.

Build the flow

1. Create each agent and define an exclusive scope in its prompt.
2. Open the agent that will route the conversation and go to Tools.
3. Add Transfer Conversation and select Add context.
4. Under When to transfer, describe one reason that is observable in the customer’s words.
5. If needed, restrict the reason under Only when by conversation tag, contact tag, channel, or inbox. Every configured condition must hold.
6. Under Where it goes, define schedules and destinations. The first matching schedule wins; Outside these hours applies when no schedule covers the current time.
7. Use Do not transfer outside the schedule when the agent should keep handling the case. Otherwise, choose another agent, a person, or the Team queue.
8. Save the tool and repeat this on the source agent for every link. There is no central squad configuration.

The model chooses only the context described under When to transfer. SquadOS resolves filters, schedules, and the destination. See every field under Transfer Conversation.

What happens at each destination

Another agent

In direct conversations, the destination agent becomes responsible and replies immediately with its own prompt, organization context, model, and tools. If the source agent wrote a short acknowledgment, that message may be delivered before the specialist’s reply.

The destination may escalate to a person on the incoming turn. To prevent cascades, it cannot transfer to another agent during that same turn; that option returns with the customer’s next message.

Person or queue

AI is disabled for the conversation and the case enters human support. A selected person receives the assignment; in the Team queue, someone must take it. The optional webhook under Advanced only applies when a human destination exists and must use HTTPS.

Hub Rooms

In Rooms, a transfer does not change ownership of the whole conversation. It creates a child run in the same thread, and the destination agent must participate in the Room. A confirmed defect in unified-configuration validation can also reject legitimate destinations; validate this path separately before relying on it.

Context continuity

Messages remain in the conversation, but do not promise that the destination agent will read the entire history. The runtime sends a recent window limited by the source agent and, on the streaming path, fetches ten messages. The summary representing older messages is a system instruction for the previous agent and is not forwarded during transfer.

For a reliable handoff:

• write the reason with enough information to guide the next action;
• keep durable facts in Notes, the contact, or your own systems, not only in old messages;
• do not require the specialist to recover an answer that may have left the window;
• test long conversations, including important facts provided near the beginning.

Cost and related controls

An agent-to-agent handoff may consume one call by the source agent and another by the destination. Each uses its own model and both count toward conversation usage. Human handoff does not invoke a second agent, although tools executed before it may have their own cost or effects.

The agent restriction configured on an inbox controls manual transfers made by a person. It does not replace destinations in Transfer Conversation. The read-only Agents that transfer here list under the destination agent’s Triggers area may also appear empty for unified-tool configurations; always inspect the source agent.

Validation checklist

Use Test Agent with the saved version and cover:

• a sentence that should select each context;
• a similar sentence that must not transfer;
• every relevant filter combination;
• inside, outside, and at the boundary of schedules, using the organization’s time zone;
• inactive, archived, or removed destination;
• a long conversation, to check which facts reach the specialist;
• human handoff and later AI reactivation;
• each Room used by the flow, separately from direct conversations;
• usage, the source agent’s message, and the destination’s first reply.

The test panel uses the real runtime: it may persist messages, consume credits, and run tools with external effects. Use safe test data.