How to design a supervisor that routes users to specialist agents

Use this guide when one conversational entry point must identify what the user needs, choose the right specialist, and pass enough context for that specialist to continue.

Concept

A supervisor is the front door for a multi-agent experience. Its primary job is not to solve every problem. Its job is to understand the request, choose the right owner, and transfer context. A specialist agent owns one business capability. A good specialist has a narrow goal, the right tools or data access, clear limitations, and a completion path. Routing is the decision that connects the user request to the correct owner. In ABL, the executable route is HANDOFF. AGENTS: is an optional roster that makes the supervisor easier to read, but it does not route by itself.

Decision guide: routing condition styles

Style	Example	Use when
Declared intent category	`WHEN: intent.category == "order_status"`	You want stable route labels for testing and reporting.
Structured condition	`WHEN: customer_id IS SET`	The route depends on known fields or variables.
Quoted semantic condition	`WHEN: "the user is asking for a refund"`	The route is best described as plain-language guidance.

Quote natural-language conditions. Unquoted text can be parsed as variable names and produce undefined-variable warnings.

Minimal working example: support supervisor project

This example is a project-level set. Put the supervisor and target agents in the same project. agents/support-supervisor.agent.abl

SUPERVISOR: Support_Supervisor
GOAL: "Route support requests to the right specialist"

AGENTS:
  account: Account_Support_Agent
  orders: Order_Status_Agent
  human: Live_Agent

INTENTS:
  account: "Account access or password help"
  order_status: "Order tracking or delivery help"
  human_help: "User asks for a person or the request is unclear"

GATHER:
  customer_id:
    prompt: "What customer ID should I use for this request?"
    type: string
    required: true

HANDOFF:
  - TO: Account_Support_Agent
    WHEN: intent.category == "account"
    PASS: [customer_id]
    SUMMARY: "Customer needs account or password support"
    RETURN: true
  - TO: Order_Status_Agent
    WHEN: intent.category == "order_status"
    PASS: [customer_id]
    SUMMARY: "Customer needs order status or delivery support"
    RETURN: false
  - TO: Live_Agent
    WHEN: intent.category == "human_help"
    PASS: [customer_id]
    SUMMARY: "Customer asks for a person or the request is unclear"
    RETURN: false

agents/account-support-agent.agent.abl

AGENT: Account_Support_Agent
GOAL: "Resolve account access and password support requests"

GATHER:
  customer_id:
    prompt: "What customer ID should I use?"
    type: string
    required: true

COMPLETE:
  - WHEN: customer_id IS SET
    RESPOND: "I can continue account support for {{customer_id}}."

agents/order-status-agent.agent.abl

AGENT: Order_Status_Agent
GOAL: "Resolve order status and delivery support requests"

GATHER:
  customer_id:
    prompt: "What customer ID should I use?"
    type: string
    required: true

COMPLETE:
  - WHEN: customer_id IS SET
    RESPOND: "I can continue order support for {{customer_id}}."

agents/live-agent.agent.abl

AGENT: Live_Agent
GOAL: "Transfer the customer to a human support queue"

COMPLETE:
  - WHEN: true
    RESPOND: "I will connect you with a human support specialist."

The supervisor gathers customer_id, then passes it with PASS. RETURN: true on account support means bounded specialist work can return to the supervisor. RETURN: false on order status and live agent means the target keeps ownership. Since none of the HANDOFF entries above declare HISTORY, each specialist now receives the full conversation history by default (the current platform default when HISTORY is omitted). Also, because each WHEN here is a single-field comparison (intent.category == "account"), an unset field simply makes the comparison evaluate false — no error, and the trace shows your literal source text.

Common variations

Plain-language routing variation

Use quoted semantic conditions when business users can describe a route more clearly in natural language than as a strict expression. Treat this as an alternative supervisor project to the previous example; do not combine both supervisors in the same deployment unless the project explicitly declares the intended entry supervisor. agents/billing-supervisor.agent.abl

SUPERVISOR: Billing_Supervisor
GOAL: "Route billing questions to the right specialist"

HANDOFF:
  - TO: Pending_Payments
    WHEN: "user is asking about payment status, unpaid balance, invoice due date, or how to pay"
    SUMMARY: "Customer needs help with pending payments or payment instructions"
  - TO: Refund_Guidance
    WHEN: "user is asking about a refund, reimbursement, returned payment, claim payout, or refund timeline"
    SUMMARY: "Customer needs refund guidance or refund status help"

agents/pending-payments.agent.abl

AGENT: Pending_Payments
GOAL: "Help customers understand pending payments and payment instructions"

COMPLETE:
  - WHEN: true
    RESPOND: "I can help with pending payments and payment instructions."

agents/refund-guidance.agent.abl

AGENT: Refund_Guidance
GOAL: "Help customers understand refund status and refund next steps"

COMPLETE:
  - WHEN: true
    RESPOND: "I can help with refund status and refund next steps."

Keep semantic routes distinct. If two routes could match the same request, customers may experience inconsistent routing.

Designing the context package

Every handoff should answer three questions.

Question	Design guidance
What does the target need to know?	Pass only useful fields, such as `customer_id`, `order_id`, `issue_summary`, or `transfer_reason`.
Why is the transfer happening?	Use `SUMMARY` so the target starts with a concise reason.
Should control come back?	Use `RETURN: true` for bounded specialist work and `RETURN: false` for permanent transfer.

Do not pass every field by default. Pass the context the target needs to continue safely.

Fallback and ambiguity design

Do not rely on the roster as a fallback. If no handoff is selected, the supervisor remains the active agent and should clarify, retry, or route to a fallback based on your design. For production supervisors:

Add a route for human help, unsupported requests, or unclear requests.
Make route descriptions mutually exclusive.
Add test utterances that intentionally look ambiguous.
Inspect traces to confirm the selected handoff target.
If your runtime configuration supports multi-intent disambiguation, verify that the user is asked to choose when a message contains multiple requests.

Verification

Validate the supervisor and all target agents together.
Send: “I forgot my password.” Expect Account_Support_Agent.
Send: “Where is my order?” Expect Order_Status_Agent.
Send: “I need to talk to someone.” Expect Live_Agent.
Confirm customer_id is gathered before routes that pass it.
Inspect trace/debug output for handoff target, return behavior, and context passed.

Production readiness checklist

Every TO target exists and has a clear owner.
Every PASS field is populated before handoff.
Every route has a distinct condition and summary.
A human or fallback route exists.
Route tests cover success, no-match, ambiguous, and escalation paths.
Trace/debug output is reviewed for each route before go-live.
Support owners agree on what RETURN: true and RETURN: false mean for their customer journey.

Common mistakes

Mistake	Why it happens	How to avoid it
Treating `AGENTS:` as routing	The roster looks like configuration.	Add `HANDOFF` entries for executable routes.
Passing unavailable context	The route references a field that was never gathered or produced.	Gather it, read it from memory, or remove it from `PASS`.
Omitting fallback	Happy-path routing looks complete.	Add human, unsupported, or clarification handling.
Overlapping route conditions	Business categories are not mutually exclusive.	Test ambiguous utterances and tighten route descriptions.

Troubleshooting

Symptom	Likely cause	What to check
No transfer happens	No handoff route was selected.	Check `HANDOFF`, `WHEN`, intent category, and fallback coverage.
Wrong target receives the user	Route conditions overlap.	Rewrite conditions and add route-specific test utterances.
Target asks for information already collected	Context was not passed or field names differ.	Check `PASS`, target `GATHER`, and trace/debug context.

​Concept

​Decision guide: routing condition styles

​Minimal working example: support supervisor project

​Common variations

​Plain-language routing variation

​Designing the context package

​Fallback and ambiguity design

​Verification

​Production readiness checklist

​Common mistakes

​Troubleshooting