> ## 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 from the welcome experience to the right agent

<Badge icon="arrow-left" color="gray">[Back to how-to guides](/agent-platform/abl/how-to/overview#conversation-entry-and-welcome-experience)</Badge>

Use this pattern when the first screen or first assistant turn should guide the user into the right specialist path.

## Concept

Welcome routing turns the first interaction into a routing signal. The signal can come from a button, an entry-page value copied into session context, or the user's first typed response. Once the signal is known, normal handoff routing should move the conversation to a specialist agent.

Do not reference a specialist agent unless it exists in the project. A routing example is only operational when the target agents are defined and the value used in `WHEN` is actually collected or set.

## Minimal working example

<AccordionGroup>
  <Accordion title="Welcome Router agent">
    ```yaml expandable=true theme={null}
    AGENT: Welcome_Router_Agent
    GOAL: "Route users from the welcome experience to the right specialist"

    GATHER:
      startup_choice:
        PROMPT: "Which option did you choose?"
        TYPE: string
        REQUIRED: true

    HANDOFF:
      - TO: Billing_Agent
        WHEN: startup_choice == "billing"
        PASS: [account_id, startup_choice]
        SUMMARY: "User selected billing from the welcome experience"
      - TO: Returns_Agent
        WHEN: startup_choice == "returns"
        PASS: [account_id, startup_choice]
        SUMMARY: "User selected returns from the welcome experience"

    ON_START:
      RESPOND: "Welcome. Choose billing or returns."
        ACTIONS:
          - BUTTON: "Billing" -> billing
            VALUE: "billing"
          - BUTTON: "Returns" -> returns
            VALUE: "returns"

    FLOW:
      entry_point: capture_choice
      steps:
        - capture_choice

    capture_choice:
      REASONING: false
      GATHER:
        startup_choice:
          PROMPT: "Which option did you choose?"
          TYPE: string
          REQUIRED: true
      THEN: COMPLETE
    ```
  </Accordion>

  <Accordion title="Billing agent">
    ```yaml theme={null}
    AGENT: Billing_Agent
    GOAL: "Handle billing questions"

    FLOW:
      entry_point: start
      steps:
        - start

    start:
      REASONING: false
      RESPOND: "I can help with billing."
      THEN: COMPLETE
    ```
  </Accordion>

  <Accordion title="Returns agent">
    ```yaml theme={null}
    AGENT: Returns_Agent
    GOAL: "Handle returns questions"

    FLOW:
      entry_point: start
      steps:
        - start

    start:
      REASONING: false
      RESPOND: "I can help with returns."
      THEN: COMPLETE
    ```
  </Accordion>
</AccordionGroup>

## How it works

The welcome message presents choices. The flow gathers `startup_choice`. The handoff conditions use that same field. The specialist agents are included so the compiler and deployment can resolve the targets.

`startup_choice` is declared both at the top level and inside `capture_choice`. Keep only the flow-step `GATHER` if the field is only ever collected inside that step; a top-level declaration is only needed if `HANDOFF` conditions must reference the field before the flow step that collects it has run in a given turn. When in doubt, declare the field once, in the flow step that actually collects it.

Since neither `HANDOFF` example above declares `HISTORY`, each specialist now receives the full conversation history by default (the current platform default when `HISTORY` is omitted).

## Common variations

### Route from a known entry topic

If the channel integration already knows the entry topic, copy it into a session variable during startup and route with that value.

<AccordionGroup>
  <Accordion title="Welcome Context Router">
    ```yaml expandable=true theme={null}
    AGENT: Welcome_Context_Router
    GOAL: "Route from startup context when the channel passes an entry intent"

    HANDOFF:
      - TO: Claims_Agent
        WHEN: entry_topic == "claims"
        PASS: [member_id, entry_topic]
        SUMMARY: "User entered from a claims landing page"
      - TO: General_Service_Agent
        WHEN: entry_topic == "general"
        PASS: [member_id, entry_topic]
        SUMMARY: "User needs general service"

    ON_START:
      SET: entry_topic = "claims"
      RESPOND: "Welcome. I will get you to the right team."

    FLOW:
      entry_point: continue
      steps:
        - continue

    continue:
      REASONING: false
      RESPOND: "Tell me what you need help with."
      THEN: COMPLETE
    ```
  </Accordion>

  <Accordion title="Claims agent">
    ```yaml theme={null}
    AGENT: Claims_Agent
    GOAL: "Handle claims questions"

    FLOW:
      entry_point: start
      steps:
        - start

    start:
      REASONING: false
      RESPOND: "I can help with claims."
      THEN: COMPLETE
    ```
  </Accordion>

  <Accordion title="General Service agent">
    ```yaml theme={null}
    AGENT: General_Service_Agent
    GOAL: "Handle general service questions"

    FLOW:
      entry_point: start
      steps:
        - start

    start:
      REASONING: false
      RESPOND: "I can help with general service."
      THEN: COMPLETE
    ```
  </Accordion>
</AccordionGroup>

## Verification

Test each startup choice and confirm the expected handoff target. In traces, inspect the startup response, the collected or set routing value, and the handoff event. Also test an unknown choice and confirm the user is asked to clarify instead of being routed incorrectly.

## Common mistakes

| Mistake                                        | Why it happens                                   | How to avoid it                                                |
| ---------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------- |
| Referencing a route variable that is never set | Button labels and route conditions drift apart.  | Gather or set the exact value used in `WHEN`.                  |
| Showing buttons without a typed fallback       | Some users type instead of clicking.             | Let the flow gather the same route value from text.            |
| Omitting target agents from the project        | The supervisor example looks complete by itself. | Define every `TO` agent or state the project-local dependency. |

## Troubleshooting

If no route matches, verify that the variable in `WHEN` has the same name as the gathered or set value. If the compiler reports missing targets, define or import the specialist agents before validating the project.

## Production readiness checklist

* Define every target specialist agent.
* Make every routing variable traceable to `GATHER`, `SET`, channel context, or tool output.
* Add a fallback for unknown or ambiguous choices.
* Pass only the fields the specialist needs.
* Test each welcome option before publishing.