> ## 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 handle messages that contain multiple user intents

[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 customers bundle several tasks in one message, such as "check my balance, pay my bill, and update my address". The `MULTI_INTENT:` section tells the agent how to detect those requests and in what order to handle them, so it does not drop the secondary ones.

## Concept

`MULTI_INTENT:` is a top-level section on an `AGENT:` or a `SUPERVISOR:`. The settings default to on. When the reasoning pipeline is on for the project, the classifier can detect several requests without any `MULTI_INTENT:` section. When the pipeline is off, a supervisor runs its classifier fallback only if the agent writes `MULTI_INTENT:` with `enabled: true`. You add the section to change how the requests are handled. See [Detect multiple intents in one user message](https://koreai.mintlify.site/agent-platform/abl/how-to/detect-multiple-intents) for how detection works.

Three layers set the values. The agent section wins over the project runtime configuration, and the project configuration wins over the platform defaults.

Three sources can find several requests in one message.

| Source | Applies to | Notes |
| - | - | - |
| Several routing calls in one model turn | A supervisor with no `BEHAVIOR` block, or with `ROLE: orchestrator` | The supervisor model calls more than one `handoff_to_` or `delegate_to_` action. `max_intents` and `confidence_threshold` do not filter these calls. Each call must still pass its route `WHEN` and `ENABLED_WHEN`. |
| The classifier in the execution pipeline | Agents with the execution pipeline on, and the project pipeline on | `confidence_threshold` drops weaker alternatives without a trace event. `max_intents` limits the queue and the menu, not a `parallel` plan or the tasks of a `sequential` plan. The classifier also rates how the requests relate. |
| Two or more `ON_INPUT` branches that match one message | Flow agents | The branch conditions decide. `max_intents` keeps the first matches and records the rest as overflow. |

A supervisor with `ROLE: router` does not make several routing calls in one turn. It routes one request at a time.

The platform rates how the requests relate as `independent`, `dependent`, or `ambiguous`. The `auto` strategy and the `parallel` strategy use this rating.

## Minimal working example

This supervisor uses the default strategy, `primary_queue`. It handles the first request now and queues the others. The specialists are short stand-ins.

```yaml expandable=true theme={null}
SUPERVISOR: Multi_Intent_Service_Supervisor
GOAL: "Handle messages that contain more than one customer request"

MULTI_INTENT:
  enabled: true
  strategy: primary_queue
  max_intents: 3
  confidence_threshold: 0.6
  queue_max_age_ms: 600000

INTENTS:
  check_balance: "Customer wants the account balance."
  pay_bill: "Customer wants to pay a bill."
  update_address: "Customer wants to change the address."

HANDOFF:
  - TO: Balance_Agent
    WHEN: intent.category == "check_balance"
    RETURN: true
    SUMMARY: "Customer wants to check the balance."

  - TO: Bill_Payment_Agent
    WHEN: intent.category == "pay_bill"
    RETURN: true
    SUMMARY: "Customer wants to pay a bill."

  - TO: Address_Update_Agent
    WHEN: intent.category == "update_address"
    RETURN: true
    SUMMARY: "Customer wants to update the address."
```

```yaml theme={null}
AGENT: Balance_Agent
GOAL: "Answer balance requests"
```

```yaml theme={null}
AGENT: Bill_Payment_Agent
GOAL: "Handle bill payments"
```

```yaml theme={null}
AGENT: Address_Update_Agent
GOAL: "Handle address changes"
```

Every property in `MULTI_INTENT:` is optional. The values above are the defaults.

Send "Check my balance and pay my bill." The supervisor routes to `Balance_Agent` first. When that specialist finishes its answer, the same reply ends with an offer for the second request, such as "Next: pay my bill. Would you like me to help with that?". The customer accepts or declines.

## How it works

1. A source in the table above finds two or more requests.
2. For the classifier and for flow branches, the platform drops requests below `confidence_threshold`. `max_intents` then limits the queue and the menu. For flow branches it keeps the first matches. It does not cap a `parallel` plan or a `sequential` plan from the classifier.
3. The platform picks a strategy. The `auto` and `parallel` strategies adjust it by the relationship rating. The table below shows the result.
4. The platform dispatches the requests with that strategy.

A `HANDOFF` entry without `HISTORY` gives each specialist the full conversation history. A project-level coordination default can change this value.

## MULTI\_INTENT properties

| Property | Type | Default | Valid range | Description |
| - | - | - | - | - |
| `enabled` | boolean | `true` | `true`, `false` | Turns multi-intent handling on or off. When it is off, a supervisor makes one routing call per turn. |
| `strategy` | string | `primary_queue` | `primary_queue`, `sequential`, `parallel`, `disambiguate`, `auto` | How the requests are handled. |
| `unknown_relationship_strategy` | string | `parallel` | `sequential`, `parallel`, `disambiguate` | The relationship to assume for several routing calls in one turn. `parallel` means independent, `sequential` means dependent, and `disambiguate` means ambiguous. |
| `max_intents` | integer | `3` | 1 to 10 | The most requests the queue holds, and the most choices a `disambiguate` menu shows. For flow branches, the most matches kept. It does not limit what the classifier detects or a `parallel` plan. |
| `confidence_threshold` | number | `0.6` | 0.0 to 1.0 | The lowest confidence for a request to count. |
| `queue_max_age_ms` | integer | `600000` | 0 to 3600000 | How long a queued request waits before the platform drops it. Use a positive value. |
| `advance_on_primary_response` | boolean | `true` | `true`, `false` | Counts the first finished answer from the primary specialist as its completion, so the next offer appears in the same reply. Set `false` to wait for a completion condition or a return. |

An invalid value fails compilation. For example, `strategy: fanout` reports `MULTI_INTENT_INVALID_STRATEGY`, and `max_intents: 11` reports `MULTI_INTENT_INVALID_MAX_INTENTS`. The compiler ignores an unknown key without a message.

### Project-level settings

These settings exist only in the project runtime configuration. Set them in the Runtime Config tab of the Studio project settings, or through the runtime configuration API.

| Setting | Values | Effect |
| - | - | - |
| `completion_signal` | `delivered_response` (default), `task_signal` | What finishes a request. With `task_signal`, the specialist must signal that it is done. |
| `list_other_requests` | `false` (default), `true` | Lets one routing call list the customer's other requests. |
| `governed_tasks`, `offer_policy`, `child_task_view`, `manage_safeguard`, `offer_resolver` | Listed in the Runtime Config tab | Governed multi-intent handling. |

Do not write these keys in an agent `MULTI_INTENT:` section. `governed_tasks`, `offer_policy`, `child_task_view`, `manage_safeguard`, and `offer_resolver` fail with error `E465`. The compiler ignores `completion_signal` and `list_other_requests` in an agent section without a message.

## Strategy reference

### primary\_queue (default)

The platform handles the first request now and queues the rest. After the primary specialist gives a finished answer, the reply ends with an offer for the next queued request. The customer can accept or decline. The platform asks before it runs any queued request. The platform drops a queued request after `queue_max_age_ms`.

### sequential

The platform runs the requests one at a time, in order. Each request gets the earlier results as context. Use it when a later request depends on an earlier one, such as confirming identity before paying a bill. The supervisor leads each request with one line of its own, so the customer knows which request runs now.

```yaml expandable=true theme={null}
SUPERVISOR: Sequential_Service_Supervisor
GOAL: "Handle dependent requests in order"

MULTI_INTENT:
  strategy: sequential
  max_intents: 4
  confidence_threshold: 0.7

INTENTS:
  verify_identity: "Customer must confirm who they are."
  pay_bill: "Customer wants to pay a bill."

HANDOFF:
  - TO: Verification_Agent
    WHEN: intent.category == "verify_identity"
    RETURN: true
    SUMMARY: "Confirm the customer identity."

  - TO: Bill_Payment_Agent
    WHEN: intent.category == "pay_bill"
    RETURN: true
    SUMMARY: "Pay the bill after identity is confirmed."
```

```yaml theme={null}
AGENT: Verification_Agent
GOAL: "Confirm customer identity"
```

```yaml theme={null}
AGENT: Bill_Payment_Agent
GOAL: "Handle bill payments"
```

* The first request starts with the words the supervisor wrote beside its routing calls, when it wrote some that the customer has not already seen. Otherwise it starts with the `multi_intent_sequential_start` message. The default is "Let's take your requests one at a time, starting with: " followed by the request.
* Each later request starts with the `multi_intent_sequential_transition` message. The default is "Next, your other request: " followed by the request. The line never says that the previous request is finished.
* The platform tells each line once, just before the first visible output of that request. A request that pauses for the customer gets its line with its question.
* A reply that the execution pipeline composes with a model carries no lead lines. The platform operator can also turn the lines off for the whole deployment.
* A specialist that needs an answer from the customer pauses the plan. The customer's reply goes to that specialist, and the plan resumes after it.
* A failed request does not stop the plan. The reply reports the failure.
* If every request fails, the customer sees a fixed message asking to try again or to ask for one request at a time.

### parallel

The platform sends the requests to specialists at the same time and merges the answers into one reply. Use it only for a supervisor whose specialists answer without asking the customer questions. A specialist that must ask a question loses its branch in a fan-out. A `DELEGATE` child cannot wait for customer input at all, so use a `RETURN: true` handoff for a specialist that needs answers from the customer.

```yaml expandable=true theme={null}
SUPERVISOR: Parallel_Service_Supervisor
GOAL: "Handle independent customer requests at the same time"

MULTI_INTENT:
  enabled: true
  strategy: parallel
  unknown_relationship_strategy: parallel

INTENTS:
  billing: "Billing and invoice questions."
  shipping: "Order delivery and tracking questions."

HANDOFF:
  - TO: Billing_Specialist
    WHEN: intent.category == "billing"
    RETURN: true
    SUMMARY: "Customer has a billing question."

  - TO: Shipping_Specialist
    WHEN: intent.category == "shipping"
    RETURN: true
    SUMMARY: "Customer has a shipping question."
```

```yaml theme={null}
AGENT: Billing_Specialist
GOAL: "Answer billing questions"
```

```yaml theme={null}
AGENT: Shipping_Specialist
GOAL: "Answer shipping questions"
```

The platform lowers `parallel` to a safer strategy when the requests are dependent or ambiguous. See [What the platform runs](#what-the-platform-runs).

### disambiguate

The platform lists the requests and asks which to handle first. The customer replies with the option number, the exact option text, a button, or a plain-language answer when a classifier is available. The customer can also reply "pause", "resume", or "cancel". The other options stay in the queue as offers. The platform asks before it runs any of them.

### auto

The platform decides from the relationship rating. `auto` never fans out. Write `strategy: parallel` when you want fan-out.

```yaml expandable=true theme={null}
SUPERVISOR: Auto_Router
GOAL: "Route requests by how the customer's requests relate"

MULTI_INTENT:
  strategy: auto
  unknown_relationship_strategy: disambiguate
  max_intents: 5

INTENTS:
  billing: "Billing and payment questions."
  technical: "Technical support and troubleshooting."

HANDOFF:
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    RETURN: true
    SUMMARY: "Billing question."

  - TO: Technical_Agent
    WHEN: intent.category == "technical"
    RETURN: true
    SUMMARY: "Technical question."
```

```yaml theme={null}
AGENT: Billing_Agent
GOAL: "Handle billing questions"
```

```yaml theme={null}
AGENT: Technical_Agent
GOAL: "Handle technical questions"
```

### What the platform runs

| Declared strategy | Independent | Dependent | Ambiguous |
| - | - | - | - |
| `primary_queue`, `sequential`, `disambiguate` | As declared. | As declared. | As declared. |
| `parallel` on a supervisor | `parallel` | `sequential` | `disambiguate` |
| `parallel` on any other agent | `sequential` | `sequential` | `disambiguate` |
| `auto` | `sequential` | `sequential` | `disambiguate` |

For several routing calls in one turn, the rating comes from `unknown_relationship_strategy`. The default `parallel` rates them independent. So `strategy: auto` with the default runs `sequential`, and `strategy: auto` with `unknown_relationship_strategy: disambiguate` asks the customer.

## Common variations

### Flow agent with two matching branches

A flow agent detects several requests when two or more `ON_INPUT` branches on the current step match the same message. This agent asks which request to handle first.

```yaml expandable=true theme={null}
AGENT: Support_Scripted_Agent
GOAL: "Handle billing and shipping requests in a scripted flow"

MULTI_INTENT:
  strategy: disambiguate
  max_intents: 2

FLOW:
  entry_point: detect
  steps:
    - detect
    - billing
    - shipping

detect:
  REASONING: false
  ON_INPUT:
    - IF: input contains "bill"
      THEN: billing
    - IF: input contains "ship"
      THEN: shipping
    - ELSE:
      RESPOND: "Please ask me about billing or shipping."
      THEN: COMPLETE

billing:
  REASONING: false
  RESPOND: "The billing team corrected the invoice."
  THEN: COMPLETE

shipping:
  REASONING: false
  RESPOND: "The shipping team confirmed the package is on schedule."
  THEN: COMPLETE
```

Send "Please fix my bill and also check the shipment." The agent lists "1. billing" and "2. shipping". Reply "2" to run the shipping step.

### Customize the prompts

Set the prompts in the `MESSAGES:` block. Add this block to a supervisor that uses `disambiguate`.

```yaml theme={null}
MESSAGES:
  multi_intent_disambiguate_header: "I see more than one request. Which should I handle first?"
  multi_intent_disambiguate_option: "Option {{index}}: {{choice}}"
  multi_intent_disambiguation_reprompt: "Reply with an option number, or say pause or cancel."
  multi_intent_disambiguation_paused: "I paused this choice. Tell me when to continue."
  multi_intent_disambiguation_cancelled: "I cancelled this choice."
  multi_intent_queued_notice: "I will handle your other requests after this one."
  multi_intent_queued_follow_up: "Next: {{next_intent}}. Should I continue?"
  multi_intent_queue_declined_ack: "Understood. What else can I help with?"
```

A supervisor that uses `sequential` can set two more keys. Add them to its own `MESSAGES:` block.

```yaml theme={null}
MESSAGES:
  multi_intent_sequential_start: "I will take your requests one at a time. First: {{request}}"
  multi_intent_sequential_transition: "Now: {{request}}"
```

| Key | Variables |
| - | - |
| `multi_intent_disambiguate_option` | `index`, `choice` (the customer's own words for the request), `label`, `intent`, `target`, `category`, `summary`, `confidence` (a whole-number percentage). |
| `multi_intent_queued_follow_up` | `next_intent`. |
| `multi_intent_queued_notice` | `next_intent`. If the notice uses the variable, it replaces the follow-up text. |
| `multi_intent_sequential_start`, `multi_intent_sequential_transition` | `request` (the request in the plan's words). |

The platform default for `multi_intent_disambiguate_option` is `{{index}}. {{choice}}`. The text `{{index}}. {{intent}} (confidence: {{confidence}})` was the earlier default. The platform treats that exact text as unset and uses the current default. Write a different option text to override the default.

## Verification

1. Validate the supervisor and every target agent together.
2. Send "Check my balance and pay my bill." Expect the first specialist to answer, and an offer for the second request in the same reply.
3. Accept the offer. Expect the second specialist to answer.
4. Send one request. Expect normal routing with no offer.
5. For `disambiguate`, expect a numbered list. Reply with a number and expect that request to run.
6. For `sequential`, expect both answers, in order, in one reply. Expect a lead line before each answer, unless a model composes the reply.

In the trace, check these events.

* `multi_intent_plan_built` is a `decision` event. It shows `strategy`, `declaredStrategy`, `relationship`, and `targets`.
* `multi_intent_queued` and `multi_intent_queue_seeded` show the queued requests for `primary_queue`.
* `multi_intent_queue_surfaced` shows the offer. `multi_intent_queue_accepted` and `multi_intent_queue_declined` show the reply.
* `multi_intent_queue_retired` with `reasonCode` `queued_intent_expired` shows a dropped request.
* `multi_intent_disambiguate_choice` shows the option the customer chose.
* `multi_intent_sequential_executed` and `multi_intent_parallel_executed` are `decision` events for those strategies.
* `multi_intent_sequential_task_failed` shows a failed request in a `sequential` plan. It carries `failedCount`.

## Production readiness checklist

* Every route has an owner, a distinct condition, and a short `SUMMARY`.
* A `RETURN: true` specialist finishes its task, so the next request can start.
* Every route used in a multi-request plan passes its `WHEN` and `ENABLED_WHEN`. The platform drops a route that fails.
* `queue_max_age_ms` fits the length of a normal session.
* For `parallel`, every specialist answers without asking the customer a question.
* For `sequential`, a specialist that needs input can pause the plan, and your test covers it.
* For `auto`, tests cover the independent, dependent, and ambiguous cases.
* `MESSAGES:` text matches your brand voice.
* Tests cover a single request, a message below `confidence_threshold`, a declined offer, and an expired offer.

## Common mistakes

| Mistake | Why it happens | How to avoid it |
| - | - | - |
| Expecting `auto` to fan out | The name suggests a smart choice. | Write `strategy: parallel`. `auto` never fans out. |
| Using `parallel` on a flow agent or a specialist that asks questions | Fan-out looks faster. | Use `sequential` or `primary_queue`. |
| Setting `strategy: parallel` and expecting it to hold | The rating is dependent or ambiguous. | Check the `strategy` in `multi_intent_plan_built`. |
| Writing the old default option text | It was copied from an older example. | Use a different text. The platform replaces the exact old default. |
| Writing `governed_tasks` or `offer_policy` in the agent section | They look like agent settings. | Set them in the project runtime configuration. The compiler reports `E465`. |
| Expecting `max_intents` to cap routing calls, the classifier, or a parallel plan | The name suggests a hard limit. | It limits the queue and the menu, and flow matches. Raise `confidence_threshold` to run fewer requests. |
| Setting `ROLE: router` and expecting several requests per turn | A router routes one request at a time. | Remove `BEHAVIOR`, or use `ROLE: orchestrator`. |

## Troubleshooting

| Symptom | Likely cause | What to check |
| - | - | - |
| A second request is never offered | The primary specialist asked a question, or `advance_on_primary_response` is `false`. | `multi_intent_delivered_turn_outcome` and the specialist's `COMPLETE` condition. |
| Requests run one after another when you set `parallel` | The agent is not a supervisor, or the rating is dependent or ambiguous. | `declaredStrategy` and `strategy` in `multi_intent_plan_built`. |
| No menu appears for `disambiguate` | The message produced one request. | `multi_intent_plan_built` and the number of `targets`. |
| A queued request disappears | It was older than `queue_max_age_ms`. | `multi_intent_queue_retired`. |
| Secondary requests are dropped | `confidence_threshold` is high, or `max_intents` is low for the queue, the menu, or flow matches. | The values in `multi_intent_plan_built`, and the intents in `pipeline_classify`. |
| The customer sees different option text | The `MESSAGES:` block is missing or used the old default. | The `MESSAGES:` block and the variables. |
| Compile error `MULTI_INTENT_INVALID_STRATEGY` | The strategy is not one of the five values. | The spelling of `strategy`. |
| Error `E465` | A project-only key is in the agent section. | Move the key to the project runtime configuration. |
| A supervisor never batches requests | `ROLE: router`, or `enabled: false`. | The `BEHAVIOR` block and `enabled`. |
| A `sequential` reply has no line before each answer | A model composed the reply, the supervisor already streamed its own words, or the platform operator turned the lines off. | The `MESSAGES:` block and the deployment setting. |


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