How to route users by detected intent

Use this pattern when a supervisor agent classifies what the user is trying to do, then hands the conversation to the specialist that owns that work.

Concept

Intent routing uses three ABL surfaces working together:

INTENTS declares the classifier categories. Each category has a description that tells the model what kinds of requests belong to it.
HANDOFF is the executable routing surface. Each entry names a target agent, the condition that triggers the handoff, and the context the child receives.
WHEN conditions on each handoff entry can be deterministic expressions (intent.category == "billing") or semantic natural-language text ("the user request is unclear"). The platform detects the form automatically: multi-word quoted text without structured operators routes through model reasoning; expressions with operators like == route through deterministic evaluation.

Two decisions shape every intent-routing supervisor:

History strategy — By default, the child agent receives the full parent conversation history (history: full). This is the platform default when history is omitted. Choose summary_only, none, auto, or last_n when the child should see less. See Common variations for the options.
Return behavior — EXPECT_RETURN: false (the default) transfers ownership permanently. EXPECT_RETURN: true pauses the parent and resumes it when the child returns. Use ON_RETURN to map child results back to parent variables.

Minimal working example

SUPERVISOR: Intent_Routing_Supervisor
GOAL: "Route customer requests to the specialist that owns the detected intent"

MEMORY:
  customer_id:
    type: string
    source: session
  account_id:
    type: string
    source: session

INTENTS:
  billing: "Questions about invoices, payment status, unpaid balances, or payment methods."
  technical_support: "Problems with product access, errors, setup, or troubleshooting."
  cancellation: "Requests to cancel, downgrade, or stop renewal."

HANDOFF:
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    CONTEXT:
      pass: [customer_id, account_id]
      summary: "Customer needs billing help."

  - TO: Technical_Support_Agent
    WHEN: intent.category == "technical_support"
    CONTEXT:
      pass: [customer_id]
      summary: "Customer needs technical support."

  - TO: Retention_Agent
    WHEN: intent.category == "cancellation"
    CONTEXT:
      pass: [customer_id, account_id]
      summary: "Customer is asking to cancel or downgrade."

  - TO: General_Service_Agent
    WHEN: "the user request is unclear or does not match billing, technical support, or cancellation"
    CONTEXT:
      pass: [customer_id]
      summary: "Customer needs general service triage."

AGENT: Billing_Agent
GOAL: "Resolve billing requests"

AGENT: Technical_Support_Agent
GOAL: "Resolve technical support requests"

AGENT: Retention_Agent
GOAL: "Handle cancellation and downgrade conversations"

AGENT: General_Service_Agent
GOAL: "Clarify and route unsupported requests"

The MEMORY section declares customer_id and account_id as session variables so the pass fields have a defined source. Any variable you pass must come from MEMORY, GATHER, a tool result, or runtime context.

How it works

The supervisor receives the user message and retains ownership until a handoff condition matches.
The platform evaluates the INTENTS classifier against the user message, producing intent.category.
HANDOFF entries are evaluated in authored order (override with PRIORITY when needed). The first matching condition wins.
The matched child receives: the pass variables, the summary text, and conversation history controlled by the history strategy. When history is omitted, the child receives the full parent conversation — this is the platform default (full).
If EXPECT_RETURN: false (the default), the child owns the conversation permanently. If EXPECT_RETURN: true, the child runs and returns control to the parent, optionally mapping result variables through ON_RETURN.
If no HANDOFF condition matches, the supervisor continues with its own GOAL. A semantic fallback entry (like the General_Service_Agent above) prevents unmatched requests from going unhandled.

Common variations

Control conversation history with `history`

When the child should not receive the full parent transcript, set history explicitly:

HANDOFF:
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    CONTEXT:
      pass: [customer_id, account_id]
      summary: "Customer needs billing help."
      history: summary_only

Value	Behavior
`full`	Platform default. The complete parent conversation history is passed.
`auto`	Uses the summary when available; falls back to the last 5 messages.
`none`	No conversation history. The child starts fresh with only `pass` variables and `summary`.
`summary_only`	Only the `summary` text is passed — no raw messages.
`{ mode: last_n, count: N }`	The last N messages from the parent are passed.

Choose summary_only or none when the child is a focused specialist that should not be influenced by earlier conversation turns. Choose full (or omit) when the child needs the complete conversation record.

Shorthand context syntax

pass, summary, and history can appear as direct siblings of the handoff entry instead of nested under CONTEXT::

HANDOFF:
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    pass: [customer_id, account_id]
    summary: "Customer needs billing help."
    history: summary_only

Both forms compile identically. The nested CONTEXT: form is preferred when you also need set or memory_grants.

Return to the parent with ON_RETURN

When a specialist should report back to the supervisor after completing its task:

HANDOFF:
  - TO: Verification_Agent
    WHEN: intent.category == "verification_needed"
    EXPECT_RETURN: true
    CONTEXT:
      pass: [customer_id]
      summary: "Customer needs identity verification."
      history: summary_only
    ON_RETURN:
      action: continue
      map:
        verified: verification_result

EXPECT_RETURN: true pauses the parent. When the child returns, ON_RETURN.map copies child variables into the parent scope. action: continue resumes the parent’s flow; action: resume_intent re-runs routing with the original user intent and the returned context. The legacy keyword RETURN is accepted as an alias for EXPECT_RETURN.

Set evaluation order with PRIORITY

When multiple handoff conditions could match the same utterance, use PRIORITY to control evaluation order. Lower values are evaluated first:

HANDOFF:
  - TO: Urgent_Support_Agent
    WHEN: intent.category == "technical_support" and priority_level == "urgent"
    PRIORITY: 0
    CONTEXT:
      pass: [customer_id]
      summary: "Urgent technical support request."

  - TO: Technical_Support_Agent
    WHEN: intent.category == "technical_support"
    PRIORITY: 1
    CONTEXT:
      pass: [customer_id]
      summary: "Technical support request."

Without PRIORITY, entries are evaluated in authored order.

Handle dispatch failures with ON_FAILURE

ON_FAILURE defines what happens when the handoff dispatch itself fails — for example, the target agent is not found or pre-transfer validation fails. It does not handle child-agent runtime errors.

HANDOFF:
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    CONTEXT:
      pass: [customer_id, account_id]
      summary: "Customer needs billing help."
    ON_FAILURE: ESCALATE

Value	Behavior
`CONTINUE`	Silently continue in the current agent.
`ESCALATE`	Trigger human escalation.
`RESPOND "message"`	Send a message and continue in the current agent.

Verification

Send a test utterance for each intent category and confirm the correct child agent is selected. Check the trace for the matched HANDOFF entry and the condition result.
Send an ambiguous utterance and confirm the fallback entry handles it. Verify the trace shows the semantic WHEN evaluation.
Inspect the trace for passed context: confirm pass variables are present in the child’s session and the summary appears in the child’s context.
If EXPECT_RETURN: true is used, verify the parent resumes and ON_RETURN.map variables appear in the parent’s session after the child returns.
Verify the history strategy by checking what conversation messages the child receives. With full (or omitted), the child should see the complete parent transcript. With summary_only, the child should see only the summary text.

Production readiness checklist

Every specialist route has a clear owner and a concise context summary.
Every pass variable has a declared source (MEMORY, GATHER, tool result, or runtime context).
Deterministic conditions use declared fields; semantic conditions are quoted as natural-language WHEN text.
Choose a history strategy appropriate for each child. The default full passes the entire parent transcript, which may include irrelevant turns and increase token usage.
Add ON_FAILURE to critical handoff entries so dispatch failures have a defined recovery path.
Fallback behavior is explicit and does not hide missing intent coverage.
Test at least one utterance per intent category, one ambiguous utterance, and one utterance outside all categories.
Temporary child agents (EXPECT_RETURN: true) produce every field mapped in ON_RETURN.
Verify handoff depth does not exceed the platform limit of 10 nested handoffs.

Common mistakes

Mistake	Why it happens	How to avoid it
Authoring a `ROUTING:` section	Confusion between conceptual routing and the ABL surface	The parser rejects `ROUTING:` and points to `HANDOFF:`. Use `HANDOFF:` for all routing entries.
Leaving semantic prose unquoted	The WHEN condition looks like an expression with undefined variables	Quote multi-word natural-language conditions so the platform routes them through model reasoning instead of expression evaluation.
Assuming the child starts with a blank slate	The default history strategy is `full`, not `none`	Set `history: none` or `history: summary_only` explicitly when you want the child to start fresh.
Passing variables without a declared source	The variables compile but have no value at runtime	Declare every `pass` variable in MEMORY, GATHER, or as a tool/runtime output before referencing it.
Routing every unmatched request to the nearest specialist	No explicit fallback; the closest label absorbs unrelated requests	Add a dedicated fallback agent with a semantic WHEN condition for unclear or unmatched requests.

Troubleshooting

Symptom	Likely cause	What to check
Child agent sees the full conversation even though only `pass` variables were declared	`history` defaults to `full` when omitted	Set `history: summary_only` or `history: none` in the CONTEXT block.
Handoff never fires for a valid utterance	WHEN condition uses an undefined variable or has a syntax error	Check that the WHEN expression references a valid field (e.g. `intent.category`) and the INTENTS section defines the expected category.
Compiler warning about ungrounded pass fields	`pass` variables are not declared in MEMORY, GATHER, or a tool output	Declare each variable source or mark it as a project-local runtime value.
Fallback agent handles requests that should match a specific intent	Intent categories overlap or the classifier description is ambiguous	Refine INTENTS descriptions to be mutually exclusive; use `PRIORITY` to control evaluation order for overlapping conditions.
Parent does not resume after child completes	`EXPECT_RETURN` is set to `false` or omitted (default)	Set `EXPECT_RETURN: true` on the handoff entry. Confirm the child agent completes and returns control.
`ON_RETURN.map` variables are missing in parent scope	Child agent does not produce the expected output variables	Verify the child agent sets the mapped variables before returning.

How to design a supervisor that routes users to specialist agents.

​Concept

​Minimal working example

​How it works

​Common variations

​Control conversation history with history

​Shorthand context syntax

​Return to the parent with ON_RETURN

​Set evaluation order with PRIORITY

​Handle dispatch failures with ON_FAILURE

​Verification

​Production readiness checklist

​Common mistakes

​Troubleshooting

​Related articles