How to route unclear or unsupported requests to a fallback agent

Back to how-to guides 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. The model chooses the fallback route when the request fits that text. 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.

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

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.

AGENT: Billing_Agent
GOAL: "Resolve billing requests"

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.
During the replay, the supervisor does not offer the fallback route again, so the customer cannot loop back to it. The platform replays at most once for each return.
The platform does not run deterministic routing during the replay. The model chooses among the routes still 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.

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

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.

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.

Verification

Validate the supervisor and all target agents together.
Send a clear billing message. Expect Billing_Agent.
Send a clear technical message. Expect Technical_Support_Agent.
Send a vague message, such as “I need help with my account.” Expect Fallback_Triage_Agent and its question.
Answer the question. Expect a resume_intent trace event, and then the matching specialist.
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.
resume_intent. Check resumeWith, resumeMessageSource, and resumeMessage to see which text the supervisor replayed.
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 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.

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

How to route unclear or unsupported requests to a fallback agent

Concept

Minimal working example

How it works

Common variations

Map a returned value to the supervisor

Always-available default route

Explain and stop

Hand the customer to a person

Verification

Production readiness checklist

Common mistakes

Troubleshooting

​Concept

​Minimal working example

​How it works

​Common variations

​Map a returned value to the supervisor

​Always-available default route

​Explain and stop

​Hand the customer to a person

​Verification

​Production readiness checklist

​Common mistakes

​Troubleshooting

Concept

Minimal working example

How it works

Common variations

Map a returned value to the supervisor

Always-available default route

Explain and stop

Hand the customer to a person

Verification

Production readiness checklist

Common mistakes

Troubleshooting