> ## 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 unclear or unsupported requests to a fallback agent

[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 the supervisor cannot choose a specialist, or when the customer asks for something outside the supported intents. A fallback agent clarifies the request or explains the limit. It does not absorb every request.

## Concept

Write the clear routes first, such as intent categories or data conditions. Write one quoted plain-language route last for requests that are vague, unsupported, or in conflict.

The fallback agent can end in one of two ways.

| Outcome | Settings | Use when |
| - | - | - |
| Clarify, then route again | `RETURN: true` with `ON_RETURN` set to `resume_intent` | A short question lets a specialist take the request. |
| Explain and stop | `RETURN: false` | The request is out of scope and the fallback can finish the conversation or hand it to a person. |

A plain-language `WHEN` is guidance for the model. Quote it. The model chooses the fallback route when the request fits that text. Outside quotes, `//` starts a comment, and a `WHEN` that holds only a comment fails to compile. A supervisor without a `BEHAVIOR` block can also answer directly instead of choosing any route. Set `BEHAVIOR` with `ROLE: router` when every message must reach a route. A router can also ask the customer one question when no route fits.

## Minimal working example

This supervisor sends billing and technical requests to specialists. It sends everything else to a triage agent. The triage agent asks one question, then returns control. The supervisor then routes the customer's answer.

```yaml expandable=true theme={null}
SUPERVISOR: Fallback_Routing_Supervisor
GOAL: "Send clear requests to specialists and unclear requests to a fallback agent"

INTENTS:
  billing: "Billing and payment requests."
  technical_support: "Product troubleshooting requests."

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

  - TO: Technical_Support_Agent
    WHEN: intent.category == "technical_support"
    RETURN: false
    SUMMARY: "Customer needs technical support."

  - TO: Fallback_Triage_Agent
    WHEN: "the request is vague, unsupported, conflicting, or missing enough information to choose a specialist"
    RETURN: true
    SUMMARY: "Ask which area the customer needs, then return so routing can resume."
    ON_RETURN:
      ACTION: resume_intent
      RESUME_WITH: latest_child_user_utterance
```

```yaml theme={null}
AGENT: Fallback_Triage_Agent
GOAL: "Find out whether the customer needs billing help or technical support"

GATHER:
  clarified_request:
    TYPE: string
    PROMPT: "Is this about billing or about a technical problem? Tell me a little more."
    REQUIRED: true

COMPLETE:
  - WHEN: clarified_request IS SET
    RESPOND: "Thanks. I am sending you to the right team."
```

These two stand-in specialists let the project compile. Replace them with your real agents.

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

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

## How it works

* The two specialist routes use `intent.category`. `INTENTS:` declares the categories. The model chooses the fallback route when neither category fits.
* The fallback agent asks its `GATHER` question. Its `COMPLETE` condition fires when `clarified_request` is set. Because the route has `RETURN: true`, control goes back to the supervisor.
* `ON_RETURN` with `ACTION: resume_intent` makes the supervisor route again after the return. `RESUME_WITH: latest_child_user_utterance` replays the customer's answer to the triage question. Without `RESUME_WITH`, the supervisor replays the original message, which was the vague one. If the fallback hands the customer back with `__return_to_parent__` and a message, the supervisor replays that message instead.
* The platform replays at most once for each return. A second return in the same turn does not replay again.
* The platform does not run deterministic routing during the replay. The model chooses among the routes still offered.
* During the replay, the supervisor hides a fallback that returned without finishing, such as one that handed the customer back with `__return_to_parent__`. A fallback that finished with a `COMPLETE` condition stays offered, so a still-vague answer can reach it again.
* During the replay, the supervisor also hides a route whose `WHEN` reads a plain session variable and is false. A route that reads `intent` stays offered.
* If the triage question gets a sensitive reply, the platform replays the original message instead.
* A `HANDOFF` entry without `HISTORY` gives the specialist the full conversation history. A project-level coordination default can change this value.
* `ON_RETURN: "resume_intent"` is the short form. It uses the default replay of the original message.

## Common variations

### Map a returned value to the supervisor

Use `MAP` when a route condition must read what the fallback learned. `MAP` copies a child field to a parent variable. The left side is the child field. The right side is the parent variable.

```yaml expandable=true theme={null}
SUPERVISOR: Mapped_Fallback_Supervisor
GOAL: "Route by a value the fallback agent returns"

MEMORY:
  SESSION:
    - clarified_area

INTENTS:
  billing: "Billing and payment requests."
  technical_support: "Product troubleshooting requests."

HANDOFF:
  - TO: Billing_Agent
    WHEN: intent.category == "billing" OR clarified_area == "billing"
    RETURN: false
    SUMMARY: "Customer needs billing help."

  - TO: Technical_Support_Agent
    WHEN: intent.category == "technical_support" OR clarified_area == "technical_support"
    RETURN: false
    SUMMARY: "Customer needs technical support."

  - TO: Fallback_Triage_Agent
    WHEN: "the request is vague, unsupported, conflicting, or missing enough information to choose a specialist"
    RETURN: true
    SUMMARY: "Ask which area the customer needs, then return so routing can resume."
    ON_RETURN:
      ACTION: resume_intent
      MAP:
        area: clarified_area
```

```yaml theme={null}
AGENT: Fallback_Triage_Agent
GOAL: "Find out whether the customer needs billing help or technical support"

GATHER:
  area:
    TYPE: enum
    OPTIONS: [billing, technical_support]
    PROMPT: "Is this about billing or technical_support?"
    REQUIRED: true

COMPLETE:
  - WHEN: area IS SET
    RESPOND: "Thanks. I am sending you to the right team."
```

The supervisor declares `clarified_area` in its own `MEMORY`. The mapped value stays in the session. A route that reads it keeps matching while the supervisor owns the conversation, so use it with specialists that keep the conversation (`RETURN: false`). If the child returns an empty value, the parent keeps its existing value.

### Always-available default route

Use `WHEN: true` on the last route when one agent can take every leftover request.

```yaml theme={null}
HANDOFF:
  - TO: Fallback_Triage_Agent
    WHEN: true
    RETURN: true
    SUMMARY: "Handle any request that no other route fits."
```

The platform does not evaluate a `true` route before the model reasons. The route stays available, and the model chooses it.

### Explain and stop

For an out-of-scope request, use `RETURN: false` on the fallback route and end the fallback agent with a `COMPLETE` condition. With `RETURN: false`, the fallback owns the conversation after the transfer. Without a `COMPLETE` condition or a human handoff, the customer cannot reach a specialist later in the same session.

### Hand the customer to a person

Route to an agent that declares `ESCALATE`. Escalation reaches a person only when the project has a human-agent connection and the `ESCALATE` block has a `routing` block with `connection`, `queue`, or `skills`. See the [ESCALATE reference](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md#escalate).

## Verification

1. Validate the supervisor and all target agents together.
2. Send a clear billing message. Expect `Billing_Agent`.
3. Send a clear technical message. Expect `Technical_Support_Agent`.
4. Send a vague message, such as "I need help with my account." Expect `Fallback_Triage_Agent` and its question.
5. Answer the question. Expect a `resume_intent` trace event, and then the matching specialist.
6. Send an out-of-scope message. Expect the fallback route, not a specialist.

In the trace, check these events.

* `handoff_condition_check` for each route the model chose. Read `result` and `evaluatedContext`.
* `handoff_completed` for each handoff attempt. Read `outcome` (`success`, `rejected`, `blocked`, `error`, or `timeout`), `cause`, and `durationMs`.
* `resume_intent`. Check `resumeWith`, `resumeMessageSource`, and `resumeMessage` to see which text the supervisor replayed. A `reasonCode` of `resume_intent_depth_limit` means the platform skipped a second replay.
* For the `MAP` variation, a `memory_error` event means the platform refused to write the mapped value.

## Production readiness checklist

* Every specialist route has an owner and a short `SUMMARY`.
* The fallback route is last, and its text is plain lowercase words.
* A returning fallback has `RESUME_WITH: latest_child_user_utterance`, or the supervisor has a route that reads the mapped value.
* Every `MAP` target is declared in the supervisor's `MEMORY`.
* A non-returning fallback ends with a `COMPLETE` condition or a human handoff.
* A human handoff has a human-agent connection and a `routing` block.
* Fallback traces are reviewed on a schedule. Add a real route for any request type that keeps landing there.
* Tests cover a clear request, a vague request, an out-of-scope request, and an answer to the triage question.

## Common mistakes

| Mistake | Why it happens | How to avoid it |
| - | - | - |
| Replaying the original vague message | `ON_RETURN` is set without `RESUME_WITH`. | Set `RESUME_WITH: latest_child_user_utterance`. |
| Mapping a field the child never sets | The `MAP` key does not match a child field. | Use the exact child field name on the left side of `MAP`. |
| Mapping to an undeclared parent variable | The parent never declares it. | Declare the target in the supervisor's `MEMORY`. |
| Writing `AND` or `OR` in the quoted fallback text | The phrase reads like plain language. | Use lowercase words. The platform evaluates uppercase `AND`, `OR`, and `NOT` as an expression. |
| Letting the fallback hide missing coverage | The fallback always answers, so gaps go unnoticed. | Review fallback traces and add routes for recurring requests. |
| Using `RETURN: false` and no way out | The fallback owns the conversation after the transfer. | Add a `COMPLETE` condition or a human handoff. |

## Troubleshooting

| Symptom | Likely cause | What to check |
| - | - | - |
| The supervisor answers instead of using the fallback | The supervisor has no `BEHAVIOR` block, so it can answer directly. | Set `ROLE: router`, or make the fallback text match the request more closely. |
| After the triage question, the customer reaches the wrong specialist | The supervisor replayed the original vague message. | `resumeMessageSource` in the `resume_intent` event. Set `RESUME_WITH`. |
| The customer reaches the triage agent twice in a row | The fallback finished with `COMPLETE`, so the replay offers it again and the model chose it. | The reply to the triage question. Add a route for that answer, or tighten the fallback `WHEN`. |
| The parent variable never changes | The `MAP` key does not match, or the child returned an empty value. | The child field name, and `memory_error` events. |
| Routing does not resume after the return | The route has `RETURN: false`, or `ON_RETURN` has no `ACTION: resume_intent`. | The route settings and the `resume_intent` event. |
| A specialist route falls through to the fallback | The intent category is not set, or the condition is false. | `handoff_condition_check` and `evaluatedContext`. |
| Warning `UNDECLARED_INTENT_CATEGORY` | A `WHEN` uses a category that `INTENTS:` does not list. | The spelling in `WHEN` and the `INTENTS:` list. |
| The specialist has more or less history than expected | `HISTORY` is omitted, so the default (`full`) applies. | Set an explicit `HISTORY` value. |


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