How to design supervisor routing with priority gates

Use this pattern when your supervisor must enforce mandatory checks — authentication, fraud screening, regulatory consent, or VIP escalation — before the reasoning model selects a business route.

Concept

A supervisor with priority gates combines two routing modes in a single HANDOFF block:

Deterministic gates use structured expressions (field comparisons, IS SET checks) and are evaluated first. They enforce hard requirements such as “the user must be authenticated before any account operation.”
Semantic routes use quoted natural-language conditions or intent-category comparisons and are evaluated after the gates pass. The reasoning model chooses the best specialist based on the user’s intent.

The compiler assigns each HANDOFF entry an evaluation priority from its position in the authored list (first entry = highest priority). The runtime sorts entries by priority and evaluates them top to bottom, selecting the first match. Placing mandatory gates at the top of the HANDOFF block guarantees they are checked before any semantic route. When a gate hands off with EXPECT_RETURN: true, the child agent runs and then returns control. The supervisor can then reprocess the original user intent (action: resume_intent) or continue where it left off (action: continue).

History default

When you omit HISTORY: on a handoff, the platform default is full — the child agent receives the entire parent conversation history. This is important to understand because:

For temporary gate agents (authentication, compliance), you may want HISTORY: auto (summary-first, falling back to the last 5 messages) or HISTORY: none to avoid passing unnecessary context.
For permanent ownership transfers (billing specialist), full is usually appropriate so the specialist has complete conversation context.

The supported history strategies are: full (default), auto, none, summary_only, and { mode: last_n, count: <n> }.

Minimal working example

SUPERVISOR: Priority_Routing_Supervisor
GOAL: "Apply mandatory gates before semantic routing"

INTENTS:
  account_help: "Account access, profile, or settings requests."
  billing: "Billing, invoice, or payment requests."
  support: "General product support requests."

MEMORY:
  SESSION:
    - is_authenticated
    - customer_id
    - customer_tier
    - account_id
    - conversation_summary

HANDOFF:
  # Gate 1: Authentication (highest priority, deterministic)
  - TO: Authentication_Agent
    WHEN: is_authenticated != true
    EXPECT_RETURN: true
    CONTEXT:
      pass: [customer_id]
      summary: "Authenticate the customer before handling account or billing data."
      history: auto
    ON_RETURN:
      action: resume_intent
      MAP:
        is_authenticated: is_authenticated

  # Gate 2: VIP escalation (semantic, checked before ordinary routes)
  - TO: Priority_Care_Agent
    WHEN: "the customer is platinum or strategic and asks for escalation"
    EXPECT_RETURN: false
    CONTEXT:
      pass: [customer_id, customer_tier, conversation_summary]
      summary: "High-priority customer asked for escalation."

  # Business routes (intent-based)
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    EXPECT_RETURN: false
    CONTEXT:
      pass: [customer_id, account_id]
      summary: "Customer needs billing help."
    ON_FAILURE: RESPOND "I was unable to connect you with billing. Let me try again."

  - TO: Account_Agent
    WHEN: intent.category == "account_help"
    EXPECT_RETURN: false
    CONTEXT:
      pass: [customer_id]
      summary: "Customer needs account help."

  - TO: Support_Agent
    WHEN: intent.category == "support"
    EXPECT_RETURN: false
    CONTEXT:
      pass: [customer_id, conversation_summary]
      summary: "Customer needs product support."

  # Fallback (lowest priority, catches unmatched messages)
  - TO: Support_Agent
    WHEN: true
    EXPECT_RETURN: false
    CONTEXT:
      pass: [customer_id]
      summary: "No specific route matched. General support fallback."

AGENT: Authentication_Agent
GOAL: "Authenticate customers"

GATHER:
  is_authenticated:
    TYPE: boolean
    PROMPT: "Is the customer authenticated?"
    REQUIRED: true

COMPLETE:
  - WHEN: is_authenticated IS SET
    RESPOND: "Authentication result captured."

AGENT: Priority_Care_Agent
GOAL: "Handle priority escalations"

AGENT: Billing_Agent
GOAL: "Resolve billing requests"

AGENT: Account_Agent
GOAL: "Resolve account requests"

AGENT: Support_Agent
GOAL: "Resolve support requests"

How it works

The supervisor receives the user message and keeps ownership until a route matches.
Intent categories, runtime context, gathered values, or tool results provide the routing evidence.
HANDOFF entries are evaluated in authored order (first = highest priority). The compiler assigns priority: 1, 2, 3, ... based on position, and the runtime sorts by priority (lower = first).
The first matching WHEN condition wins. Deterministic gates at the top of the list are always checked before semantic or intent-based routes below them.
When a handoff fires, the child agent receives the PASS fields, the summary, and conversation history according to the HISTORY strategy. The default strategy is full (entire parent history). Use HISTORY: auto or HISTORY: none when you want the gate agent to receive less context.
If the child is temporary (EXPECT_RETURN: true), it returns through ON_RETURN. The supervisor then either resumes intent routing (action: resume_intent) or continues its current flow (action: continue).
If the child owns the conversation (EXPECT_RETURN: false), it remains the active agent permanently.

Common variations

Authentication gate before account or billing specialists

Use EXPECT_RETURN: true with ON_RETURN: action: resume_intent so the supervisor reprocesses the original user intent after authentication completes. Set HISTORY: auto to give the auth agent only a summary instead of full conversation history.

HANDOFF:
  - TO: Auth_Gate
    WHEN: is_authenticated != true
    EXPECT_RETURN: true
    CONTEXT:
      pass: [session_token]
      summary: "Verify user identity before proceeding."
      history: auto
    ON_RETURN:
      action: resume_intent
      MAP:
        is_authenticated: auth_result

VIP escalation route before ordinary queue routing

Place the VIP check after mandatory gates but before standard business routes. Use a quoted natural-language WHEN condition when the routing evidence comes from business context rather than a single ABL field.

HANDOFF:
  - TO: VIP_Concierge
    WHEN: "the customer has a platinum or enterprise tier and is requesting priority service"
    EXPECT_RETURN: false
    CONTEXT:
      pass: [customer_id, customer_tier, account_value]
      summary: "VIP customer requesting priority service."

Compliance gate with explicit PRIORITY field

When you need to override the default authored-order priority, use the PRIORITY: field. Lower values are evaluated first.

HANDOFF:
  - TO: Compliance_Check
    WHEN: transaction_amount > 10000
    PRIORITY: 0
    EXPECT_RETURN: true
    CONTEXT:
      pass: [transaction_id, transaction_amount, customer_id]
      summary: "High-value transaction requires compliance review."
      history: none
    ON_RETURN:
      action: continue
      MAP:
        compliance_cleared: review_result

  - TO: Payment_Agent
    WHEN: intent.category == "payment"
    PRIORITY: 10
    EXPECT_RETURN: false
    CONTEXT:
      pass: [customer_id, transaction_id]
      summary: "Process payment request."

CONTEXT shorthand

PASS, SUMMARY, and HISTORY can also appear as direct siblings of the handoff entry instead of nested under CONTEXT. Both forms are equivalent.

HANDOFF:
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    PASS: [customer_id, account_id]
    SUMMARY: "Customer needs billing help."
    HISTORY: full
    EXPECT_RETURN: false

Verification

Parse the ABL and confirm there are no parser errors or warnings.
Compile the ABL and confirm there are no compiler errors. Review any warnings about undeclared field references — these indicate variables that must be supplied at runtime from context, tool results, or project configuration.
Test each routing path with a representative utterance:
- For the authentication gate: send any message when is_authenticated is not set. Expect the supervisor to route to Authentication_Agent.
- For the VIP route: send “I need to speak with someone about my enterprise account” when the customer tier is platinum. Expect Priority_Care_Agent.
- For intent routes: send “I have a billing question” and confirm the Billing_Agent is selected.
- For the fallback: send a message that does not match any defined intent. Confirm Support_Agent is selected as the fallback.
After the auth gate returns, send a billing-related message and confirm the supervisor re-routes to Billing_Agent (validating resume_intent behavior).
Inspect routing traces for: selected target, condition result, passed context fields, history strategy applied, and return behavior when EXPECT_RETURN: true is used.

Production readiness checklist

Every specialist route has a clear owner and a concise context summary.
All variables referenced in PASS fields are declared in MEMORY:SESSION or are explicitly documented as project-local assumptions that will be populated at runtime.
Deterministic conditions use declared, gathered, tool-result, runtime, or returned fields.
Semantic conditions are quoted as natural-language WHEN text.
Temporary child agents produce every field mapped in ON_RETURN.
A fallback route with WHEN: true catches unmatched messages explicitly.
ON_FAILURE is set on critical routes to handle dispatch failures gracefully.
The HISTORY strategy is chosen deliberately for each handoff. Use full for permanent transfers, auto or none for temporary gates that should not receive full conversation context.
Fallback behavior is explicit and does not hide missing intent coverage.
Routes are tested with representative utterances for each path, including the fallback and the post-gate resume path.

Common mistakes

Mistake	Why it happens	How to avoid it
Omitting HISTORY on a gate handoff and leaking full conversation context to a temporary child agent	The default HISTORY strategy is `full`, which passes the entire parent conversation to the child	Set `HISTORY: auto` or `HISTORY: none` on temporary gate agents that do not need the full conversation
Making the specialist responsible for checking a mandatory parent gate	It seems simpler to let each child check auth, but this duplicates logic and risks inconsistency	Keep mandatory gates in the supervisor HANDOFF block, above all specialist routes
Mapping returned fields that the child agent does not produce	ON_RETURN MAP references a field name that is not gathered, set, or returned by the child	Ensure the child agent declares or produces every field referenced in ON_RETURN MAP
Using an unquoted expression for externally supplied values	Unquoted conditions are parsed as structured expressions and may produce undefined-variable warnings	Use a quoted natural-language condition when the routing evidence is external business context, or declare the variables in MEMORY:SESSION
No fallback route for unmatched messages	All WHEN conditions are specific, so an unmatched message has no explicit path	Add a `WHEN: true` fallback as the last HANDOFF entry
PASS fields not declared in MEMORY:SESSION	The compiler resolves PASS fields from session memory for type/description metadata; undeclared fields fall back to type=string	Declare all PASS variables in MEMORY:SESSION for clear typing and documentation

Troubleshooting

Symptom	Likely cause	What to check
Gate agent fires on every message even after authentication succeeds	ON_RETURN MAP does not write back the gate result to the parent session variable	Verify that the MAP key matches the child’s output field and the parent’s session variable name
Semantic route is selected before the deterministic gate	The semantic route appears above the gate in the HANDOFF block (lower authored position = higher priority)	Move mandatory gates to the top of the HANDOFF block
Child agent responds without conversation context	HISTORY is set to `none` or `summary_only`, or the summary is empty when using `auto`	Check the HISTORY strategy on the handoff entry; use `full` or provide a non-empty summary for `auto`
Compiler warning about undeclared field reference in WHEN condition	The variable in the WHEN expression is not in GATHER, MEMORY:SESSION, or built-in variables	Declare the variable in MEMORY:SESSION, or verify it will be supplied at runtime from context or tool results
resume_intent does not re-route after gate return	The ON_RETURN action is set to `continue` instead of `resume_intent`, or the MAP does not update the gate variable	Set `action: resume_intent` in ON_RETURN and verify the MAP updates the condition variable (e.g., is_authenticated)
Unmatched messages produce no response	No fallback route exists in the HANDOFF block	Add a `WHEN: true` fallback entry as the last HANDOFF entry

Related articles

​Concept

​History default

​Minimal working example

​How it works

​Common variations

​Authentication gate before account or billing specialists

​VIP escalation route before ordinary queue routing

​Compliance gate with explicit PRIORITY field

​CONTEXT shorthand

​Verification

​Production readiness checklist

​Common mistakes

​Troubleshooting