> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How to route users by detected intent

[Back to how-to guides](https://koreai.mintlify.site/agent-platform/abl/how-to/overview.md#routing-and-multi-agent-orchestration)

Use this pattern when a supervisor must work out what the customer wants and hand the conversation to the specialist that owns that work.

## Concept

Intent routing uses two ABL sections.

* `INTENTS:` lists the categories and describes each one. The descriptions guide the classifier and the supervisor model. The section is optional. Without it, the compiler takes the categories from the `intent.category` comparisons in your `WHEN` rules.
* `HANDOFF:` holds the routes. Each entry names a target agent, a `WHEN` condition, and the context the target receives.

A route reads the category through `intent.category`, for example `WHEN: intent.category == "billing"`.

### How the platform picks a route

| Situation | What decides the route |
| - | - |
| The `EXECUTION.pipeline` classifier runs and is confident. | The platform tests the `HANDOFF` entries in authored order. The first `WHEN` that is true selects the target. The handoff happens without a reasoning turn. |
| The supervisor model chooses a route. | The model calls the route action and states the intent category. The platform checks the `WHEN` of that entry before it transfers the conversation. |
| A child that was expected to return finishes. | The platform tests the `HANDOFF` conditions again in authored order. The first match wins. |

The pipeline is optional. It runs only when the project enables it, the agent does not opt out, and a pipeline model is available. Without it, the model path decides. See How to use EXECUTION.pipeline for agent routing, classification, and short-circuiting.

### Condition styles

| Style | Example | Behavior |
| - | - | - |
| Expression | `intent.category == "billing"` | The platform enforces it. A route whose expression is false is refused. |
| Quoted plain-language phrase | `"the customer asks about a refund"` | Guidance for the model. The platform accepts the model's choice. |
| Always true | `true` | The route is always available. Use it for the fallback. |

Quote plain-language text. Unquoted text is read as variable names and produces undefined-variable warnings.

A `//` outside quotes starts a comment in a `WHEN`. A `WHEN` that holds only a comment fails to compile with the message `WHEN is required`.

The pipeline evaluates a quoted phrase as a string that is always true. A quoted route placed above an `intent.category` route captures every message the pipeline classifies. Put quoted routes after the `intent.category` routes.

### Order is priority

The position of an entry in `HANDOFF:` sets its priority. The first entry has the highest priority. The model sees the position as `[Priority N]` in the route description. The `PRIORITY:` field is read and then ignored. Move the entry instead.

### Decisions for every route

* **History.** The target receives the full conversation history unless you set `history`. A project default can change that value. See [Control conversation history](#control-conversation-history-with-history).
* **Return.** `EXPECT_RETURN: false` is the default. The target keeps the conversation. `EXPECT_RETURN: true` pauses the supervisor until the target returns. See [Return to the supervisor with ON\_RETURN](#return-to-the-supervisor-with-on_return).

## Minimal working example

This example is a project-level set. Put the supervisor and the four target agents in the same project. The targets are short stand-ins for your real agents.

`agents/intent-routing-supervisor.agent.abl`

```yaml expandable=true theme={null}
SUPERVISOR: Intent_Routing_Supervisor
GOAL: "Route customer requests to the specialist that owns the detected intent"

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: true
    CONTEXT:
      pass: [customer_id]
      summary: "The request did not match a specialist. Customer needs general service triage."
```

`agents/billing-agent.agent.abl`

```yaml theme={null}
AGENT: Billing_Agent
GOAL: "Resolve billing requests"
```

`agents/technical-support-agent.agent.abl`

```yaml theme={null}
AGENT: Technical_Support_Agent
GOAL: "Resolve technical support requests"
```

`agents/retention-agent.agent.abl`

```yaml theme={null}
AGENT: Retention_Agent
GOAL: "Handle cancellation and downgrade conversations"
```

`agents/general-service-agent.agent.abl`

```yaml theme={null}
AGENT: General_Service_Agent
GOAL: "Clarify and route requests that no specialist owns"
```

The platform fills each `PASS` field from the parent's data when the parent holds a value, for example from caller data or a gathered field. Otherwise the supervisor model fills it from what the customer said. When neither has a value, the target must collect it.

The `summary` text also supports `{{field}}` interpolation from the supervisor's data.

## How it works

1. The supervisor receives the message and keeps the conversation until a route fires.
2. The platform assigns an intent category. With the pipeline, the classifier assigns it. Without the pipeline, the model states it when it calls a route.
3. The platform checks the `WHEN` of the selected route. An expression must be true. A refused route returns a message to the model, which then tries another route or asks the customer.
4. The target receives the `PASS` values, the `summary`, and the history that the `history` setting allows.
5. With `EXPECT_RETURN: false`, the target keeps the conversation. With `EXPECT_RETURN: true`, the supervisor pauses and resumes when the target returns.
6. When no route fires, the supervisor stays active. The `WHEN: true` entry in the example is the fallback.

A chain of nested handoffs can reach a depth of 10 before the platform refuses the next one. The platform also refuses a handoff to an agent that is already in the active chain. A child that returns to the supervisor waiting for it is not a loop.

## Common variations

### Control conversation history with `history`

When the target does not need the full transcript, set `history` on the entry. Add it inside `CONTEXT:`.

```yaml theme={null}
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    CONTEXT:
      pass: [customer_id, account_id]
      summary: "Customer needs billing help."
      history: summary_only
```

| Value | Behavior |
| - | - |
| `full` | Default. The target receives the complete parent history. |
| `auto` | The target receives the summary when one exists. Otherwise it receives the last 5 messages. |
| `none` | The target receives no history. It starts with the `PASS` values and the summary. |
| `summary_only` | The target receives only the summary text. |
| `last_n` | The target receives the last N messages. Write it as a block: `history:`, then `mode: last_n` and `count: 6` on indented lines. |

Write `last_n` as a block. The inline form `history: { mode: last_n, count: 6 }` compiles without a warning and has no effect, so the target receives the full history.

Use `summary_only` or `none` for a focused specialist. Use `full` when the target needs the whole record.

### Write context as sibling keys

`PASS`, `SUMMARY`, and `HISTORY` can sit directly under the entry instead of inside `CONTEXT:`. Both forms compile to the same route.

```yaml theme={null}
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    PASS: [customer_id, account_id]
    SUMMARY: "Customer needs billing help."
    HISTORY: summary_only
```

Use `CONTEXT:` when you also need `set` or `memory_grants`.

### Return to the supervisor with ON\_RETURN

Use `EXPECT_RETURN: true` when a specialist does bounded work and the supervisor continues afterward. In this example, a verification agent returns before billing help starts.

```yaml theme={null}
  - TO: Verification_Agent
    WHEN: intent.category == "billing" AND verification_result != true
    EXPECT_RETURN: true
    CONTEXT:
      pass: [customer_id]
      summary: "Customer needs identity verification before billing help."
      history: summary_only
    ON_RETURN:
      action: resume_intent
      map:
        verified: verification_result

  - TO: Billing_Agent
    WHEN: intent.category == "billing" AND verification_result == true
    CONTEXT:
      pass: [customer_id, account_id]
      summary: "Verified customer needs billing help."
```

`map` copies a child field into a parent field. Write the child field first, then the parent field: `verified: verification_result` copies the child's `verified` into the parent's `verification_result`. The child must gather or produce `verified`. With a `map`, only the mapped fields return. Without a `map`, the platform copies all gathered child data back.

`action: resume_intent` runs routing again against the original request with the returned context. The replay runs one level deep. A second return inside the replay does not replay again, and the trace shows `resume_intent` with `reasonCode: resume_intent_depth_limit`. `action: continue` resumes the supervisor's current flow.

While a returning child is active, the platform can also send the customer back to the supervisor. With the pipeline on, the classifier checks each reply against the supervisor routes in authored order. When another agent's route matches with enough confidence, the conversation returns to the supervisor. The trace shows a `digression` event with `action: return_to_parent`. The supervisor `EXECUTION.pipeline` block sets the threshold in `parentReturn`. See How to configure EXECUTION.pipeline models, modes, thresholds, and fallbacks.

`RETURN` is accepted as an older name for `EXPECT_RETURN`. `ON_RETURN` without `EXPECT_RETURN: true` produces the warning `HANDOFF_ON_RETURN_WITHOUT_RETURN`.

### Put specific routes before general routes

When two routes can match the same message, place the specific route first. The first entry has the highest priority.

```yaml theme={null}
  - TO: Account_Billing_Agent
    WHEN: intent.category == "billing" AND session.identityTier == 2
    CONTEXT:
      pass: [customer_id, account_id]
      summary: "Verified customer needs billing help."

  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    CONTEXT:
      pass: [customer_id]
      summary: "Unverified customer needs general billing information."
```

`session.identityTier` is `2` after the channel verifies the identity. The route is false for an anonymous customer, so that customer reaches `Billing_Agent`.

### Add a plain-language route

Use a quoted phrase for a request type that has no category. Place it after the `intent.category` routes.

```yaml theme={null}
  - TO: Refund_Specialist
    WHEN: "the customer asks about a refund, a returned payment, or a refund timeline"
    CONTEXT:
      pass: [customer_id, account_id]
      summary: "Customer needs refund help."
```

Keep the phrase in lowercase words. A quoted phrase is read as an expression when it contains uppercase `AND`, `OR`, or `NOT`, a comparison symbol, `IS SET`, a word such as `contains`, or a word directly followed by `(`.

### Handle dispatch failures with ON\_FAILURE

`ON_FAILURE` runs when the handoff fails before the target accepts it, for example when validation fails. It does not handle errors that the target raises later. A route that the `WHEN` guard refuses does not run `ON_FAILURE`. The model receives the refusal instead.

```yaml theme={null}
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    CONTEXT:
      pass: [customer_id, account_id]
      summary: "Customer needs billing help."
    ON_FAILURE: RESPOND "I could not reach billing. Please try again in a moment."
```

| Value | Behavior |
| - | - |
| `CONTINUE` | The supervisor continues. This is the default. |
| `ESCALATE` | The session is marked as escalated. A person receives the conversation only when the project has a human-agent connection and an `ESCALATE` block with a `routing` block. See the [ESCALATE reference](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md#escalate). |
| `RESPOND "message"` | The supervisor sends the message and continues. |

A bare quoted string such as `ON_FAILURE: "message"` fails to compile with `INVALID_HANDOFF_FAILURE_ACTION`.

## Verification

1. Send one test message for each category. Open the trace. Find the `handoff_condition_check` events for the turn. Confirm that the expected route has `result: true`.
2. Send a message that matches no category. Confirm that the `WHEN: true` route receives it.
3. When the pipeline is on, find the `pipeline_classify` and `pipeline_routing_resolve` events. Confirm the category and the matched route.
4. Check the `handoff` trace event. Confirm the `PASS` values and the summary in its `context`. Check `seededFields` in `handoff_context_seed` to see which fields reached the target. Check `handoff_context_pass_resolved` only for values taken from the customer's message.
5. Check the history. With `full`, the target sees the full parent transcript. With `summary_only`, the target sees the summary only.
6. For `EXPECT_RETURN: true`, confirm the supervisor resumes and the mapped fields appear in the supervisor's session data.
7. Find the `handoff_completed` event for each attempt. Check `outcome` (`success`, `rejected`, `blocked`, `error`, or `timeout`) and `durationMs`. A route that the `WHEN` guard refuses shows `blocked`. When `ON_FAILURE` runs, find the `handoff_failure` event for the `phase` and the `action`.

## Production readiness checklist

* Every `TO` target exists in the project.
* Every `PASS` field has a source: parent data, caller data, a gathered field, or a value the customer states.
* Every `intent.category` value in a `WHEN` appears in `INTENTS:`. The compile shows no `UNDECLARED_INTENT_CATEGORY` warning.
* Specific routes come before general routes. Quoted routes come after `intent.category` routes.
* Each route sets `history` on purpose. The default `full` passes the whole transcript and uses more tokens.
* A `WHEN: true` fallback exists, or the supervisor can answer on its own.
* Critical routes have an `ON_FAILURE` policy.
* Every field in an `ON_RETURN` `map` exists in the child.
* Tests cover one message per category, one ambiguous message, and one message outside every category.
* Monitoring covers `handoff_completed` events with the outcomes `error` and `timeout`.

## Common mistakes

| Mistake | Why it happens | How to avoid it |
| - | - | - |
| Writing a `ROUTING:` section. | Routing sounds like its own section. | The parser rejects `ROUTING:` with error `E104`. Use `HANDOFF:`. |
| Setting `PRIORITY:` to reorder routes. | The field looks like it controls order. | The platform ignores it. Reorder the entries. |
| Leaving a plain-language `WHEN` unquoted. | The text looks like a condition. | Quote the text. |
| Placing a quoted route above `intent.category` routes. | The pipeline treats a quoted phrase as true. | Put quoted routes last. |
| Expecting the child to start fresh. | The default history is `full`. | Set `history: none` or `summary_only`. |
| Writing `history: { mode: last_n, count: 6 }` on one line. | The inline form looks valid. | Write `mode` and `count` on indented lines. |
| Writing the `map` in the wrong direction. | The parent field seems to come first. | Write `child_field: parent_field`. The compiler reports `UNKNOWN_HANDOFF_RETURN_FIELD`. |
| Routing every unmatched request to the nearest specialist. | The route has no explicit fallback. | Add a `WHEN: true` fallback agent. |

## Troubleshooting

| Symptom | Likely cause | What to check |
| - | - | - |
| A valid message reaches the wrong agent. | Two routes can match, and the earlier entry wins. | The entry order. Move the specific route up. |
| A route never fires. | The category is missing from `INTENTS:`, or the expression is false. | `UNDECLARED_INTENT_CATEGORY`, and `result` in `handoff_condition_check`. |
| The model reports that a handoff is blocked. | The route's expression is false for the current data. | The `condition` and `evaluatedContext` in `handoff_condition_check`. |
| The target sees the whole conversation. | `history` is omitted, so the default `full` applies. | `history` on the entry. |
| The target asks for a value that you passed. | The `PASS` field has no value in the parent. | Where the parent gets the value. Gather it or read it from caller data. |
| The supervisor does not resume after the child. | `EXPECT_RETURN` is `false` or omitted. | `EXPECT_RETURN: true` on the entry. |
| Mapped fields are missing after the return. | The `map` direction is reversed, or the child never sets the field. | `UNKNOWN_HANDOFF_RETURN_FIELD`, and the child's `GATHER` section. |
| A refund question reaches the fallback, not the refund route. | The quoted route is below a route that already matched, or the phrase reads as an expression. | The entry order and the phrase wording. |
| The compile fails with `WHEN is required`. | The `WHEN` holds only a `//` comment. | Write the condition before the comment. |
| The customer leaves a returning child after one reply. | The classifier matched another supervisor route above the return threshold. | The `digression` event and `parentReturn` on the supervisor. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.