> ## 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 clarify before routing to a specialist agent

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

Use this when a request is short, vague, or missing the one detail that decides which specialist owns it.

## Concept

Clarifying means the customer answers one question before a route is chosen. ABL has three ways to ask. Pick by who controls the question.

| Approach | Who asks | Use when |
| - | - | - |
| Router supervisor | The model, through a built-in clarification action | Any wording is acceptable and the categories are easy to describe in plain language. |
| Entry agent with an enum `GATHER` in a `FLOW` step | The runtime, as a scripted step | You need a fixed list of answers, validation, and routes that do not depend on the model. |
| Fallback specialist | A specialist agent | Clarification needs several questions. See the fallback agent HowTo. |

A `GATHER` block on a supervisor does not pause the conversation to ask a question. The supervisor model chooses a route on every turn. A supervisor `GATHER` field fills from the routing call, and only when the field sets `infer: true`. A route `WHEN` that reads a supervisor `GATHER` field stays false while the field is empty. The runtime then refuses the route. Use one of the approaches in the table instead.

## Minimal working example: router supervisor

A `router` supervisor cannot answer in text. When no route fits the request, the model calls a built-in clarification action with one question. The runtime sends that question to the customer and ends the turn. The next message goes through routing again.

This example is a project-level set. The two specialists are short stand-ins for your real agents.

```yaml expandable=true theme={null}
SUPERVISOR: Support_Router
GOAL: "Route each request to billing or technical support, and ask one question when the request does not say which"
PERSONA: "Brief and polite. Ask only for the detail that decides the specialist."

BEHAVIOR:
  ROLE: router

INTENTS:
  billing: "Charges, invoices, refunds, or payment methods."
  technical_support: "Errors, outages, or product setup problems."

HANDOFF:
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    RETURN: false
    SUMMARY: "Customer needs help with a billing question."

  - TO: Technical_Support_Agent
    WHEN: intent.category == "technical_support"
    RETURN: false
    SUMMARY: "Customer needs help with a technical problem."

AGENT: Billing_Agent
GOAL: "Resolve billing questions"

AGENT: Technical_Support_Agent
GOAL: "Resolve technical problems"
```

## How the router asks

* `INTENTS:` lists the categories. A `WHEN` that reads `intent.category` makes the model state a category when it calls the route.
* The model sees the clarification action next to the routes. It uses the action only when no route fits. The action takes one `message`, which is the question.
* The `PERSONA` text shapes how the question reads. The action has no other settings.
* The runtime offers the action only to supervisors with `BEHAVIOR: ROLE: router` and at least one route. A supervisor with no `BEHAVIOR` block can answer in text, so it asks in plain words and has no action.
* A route with no `HISTORY` passes the full conversation history. The specialist sees the question and the answer. A project default can change this value.
* The question does not set any variable. The customer's answer is a normal message.

## Ask with a fixed list of answers

Use an entry agent when the answer must be one of a known set. This example is a separate project. It replaces the router supervisor. The runtime asks the prompt, waits, and checks the answer against `OPTIONS`. When the step ends, the runtime checks each route `WHEN` in order. The first true route runs.

```yaml expandable=true theme={null}
AGENT: Support_Entry_Agent
GOAL: "Ask which kind of help the customer needs, then send them to the matching specialist"
PERSONA: "Brief and polite"

HANDOFF:
  - TO: Billing_Agent
    WHEN: route_topic == "billing"
    PASS: [route_topic]
    SUMMARY: "Customer chose billing."
    RETURN: false
  - TO: Technical_Support_Agent
    WHEN: route_topic == "technical_support"
    PASS: [route_topic]
    SUMMARY: "Customer chose technical support."
    RETURN: false
  - TO: General_Service_Agent
    WHEN: route_topic == "other"
    PASS: [route_topic]
    SUMMARY: "Customer chose something else and needs triage."
    RETURN: false

FLOW:
  entry_point: ask_topic
  steps:
    - ask_topic

ask_topic:
  REASONING: false
  GATHER:
    route_topic:
      PROMPT: "What do you need help with: billing, technical_support, or other?"
      TYPE: enum
      OPTIONS: [billing, technical_support, other]
      REQUIRED: true
  THEN: COMPLETE

AGENT: Billing_Agent
GOAL: "Resolve billing questions"

AGENT: Technical_Support_Agent
GOAL: "Resolve technical problems"

AGENT: General_Service_Agent
GOAL: "Ask follow-up questions and route unsupported requests"
```

* `route_topic` comes from the `GATHER` field. Each route reads it and passes it on.
* An answer outside `OPTIONS` fails validation. The step asks again and no route runs.
* Give every option a route. A valid value with no matching route reaches `THEN: COMPLETE` and the session ends.
* The `other` option is the way out for unsupported requests. Point it at an agent that can triage.
* A quoted plain-language `WHEN` never matches in this scripted check. Use exact values here.

## Ask which of several requests to handle first

A message can hold more than one request. Multi-intent handling is on by default. The default `primary_queue` strategy serves the main request and queues the others. To ask the customer instead, set the strategy on the router supervisor. Add this block before the first `AGENT:` line of the router example.

```yaml theme={null}
MULTI_INTENT:
  strategy: disambiguate
  max_intents: 2
```

The runtime shows the choices and waits for the customer to pick one. See the multiple intents HowTo for the other strategies.

Without `MULTI_INTENT`, the runtime can still ask one scope question. This applies to the first customer message of a supervisor that has several `INTENTS` categories and conditional routes, when the execution pipeline is not enabled. The message must hold more than one request, and at least one request must have no matching category or a confidence below the multi-intent threshold. The runtime hides every route for that turn, asks one question, and keeps all requests in view. The trace shows a `decision` event with `multi_intent_scope_clarification_required`.

## Write quoted fallback text carefully

A quoted `WHEN` such as `WHEN: "the request does not fit any listed category"` is guidance for the model. It works when the model picks that route. It never routes on its own.

The runtime reads a quoted phrase as an expression when it has an uppercase `AND`, `OR`, or `NOT`. The same happens with a comparison symbol or a word such as `contains`. Write fallback text in lowercase words with no symbols.

A `//` outside quotes starts a comment in a route `WHEN` or `ENABLED_WHEN`. A condition that holds only a comment fails to compile with `WHEN is required`. Put notes on their own line above the route.

## Verification

Router supervisor:

1. Send "I need help". Expect one question and no handoff. The trace shows a `tool_call` named `__clarify_routing__`.
2. Answer "I was charged twice". Expect a handoff to `Billing_Agent`. The trace shows `handoff_condition_check` with `result: true`.
3. Send "My app shows error 500". Expect `Technical_Support_Agent` with no question.

Entry agent:

1. Start a session. Expect the `route_topic` prompt.
2. Answer "pizza". Expect a validation message and the prompt again. No `handoff` event appears.
3. Answer "billing". Expect a `handoff` event to `Billing_Agent` with `reasonCode: handoff_permanent`. The preceding `handoff_condition_check` shows `source: flow_transition` and `currentStep: ask_topic`.
4. Repeat with `technical_support` and `other`.

## Production readiness checklist

* Every route target exists and has a clear owner.
* The router supervisor has `BEHAVIOR: ROLE: router`. Without it, no clarification action exists.
* Every category in a `WHEN` is declared in `INTENTS:`.
* Every `OPTIONS` value in the entry agent has a route.
* One route leads to an agent that handles unsupported requests.
* Tests cover a clear request, a vague request, an invalid answer, and a message with two requests.
* Quoted fallback text uses lowercase words and no comparison symbols.
* The trace shows the question or the validation message before the handoff.

## Common mistakes

| Mistake | Why it happens | How to avoid it |
| - | - | - |
| Putting the clarification `GATHER` on a supervisor | The field looks like a question step. | Use a router supervisor or an entry agent with a `FLOW` step. |
| Routing on a supervisor `GATHER` field | The route `WHEN` reads a value the supervisor never stored. | Route on `intent.category`, or gather the field in an entry agent. |
| Expecting a router with no `BEHAVIOR` block to use the action | The action needs the `router` role. | Set `BEHAVIOR: ROLE: router`. |
| Leaving an `OPTIONS` value with no route | The list and the routes drift apart. | Compare the two lists on every change. |
| Asking a long form | Extra fields feel safe. | Ask for the one value that decides ownership. |
| Writing `AND` or `OR` in uppercase inside quoted text | The phrase reads like plain language. | Use lowercase words. |
| Writing only a comment after `WHEN:` | A placeholder comment stands in for the condition. | Write a condition. A comment-only `WHEN` fails to compile. |

## Troubleshooting

| Symptom | Likely cause | What to check |
| - | - | - |
| The supervisor never asks a question | The supervisor is not a `router`, or a route always fits. | The `BEHAVIOR` block, `INTENTS:` text, and route wording. |
| The supervisor routes with no question for a vague request | The category descriptions are broad. | Narrow the `INTENTS:` descriptions. |
| The trace says `Handoff to X blocked: WHEN condition not met` | The route reads a field that is not set. | `handoff_condition_check` `evaluatedContext` and `route_condition_unresolved`. |
| The entry agent asks again after a valid answer | The answer is not an exact `OPTIONS` value. | The `OPTIONS` list and the prompt wording. |
| The session ends after the answer | No route matches the value. | Add a route for every `OPTIONS` value. |
| The specialist asks for what the customer already said | The route passes no field, or the history is limited. | `PASS`, `HISTORY`, and the specialist `GATHER`. |
| A fallback route behaves unpredictably | The quoted text has uppercase `AND`, `OR`, or `NOT`. | Rewrite the phrase in lowercase words. |


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