> ## 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 by tool result, profile lookup, or remembered state

[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 route depends on data your project already holds about the customer, such as account tier, open case, fraud risk, entitlement, or a remembered preference. The customer's words do not decide the route.

## Concept

A supervisor can route on data it loads before the first routing decision. Two sources work.

| Source | How the data arrives | How a route reads it |
| - | - | - |
| A lookup tool | `ON_START` calls a read-only tool and binds the result with `AS`. | `profile.tier` |
| Persistent memory | A `RECALL` at `session:start` loads stored facts. | `user.loyalty_tier` |

Each `HANDOFF` has a `WHEN` condition. The platform evaluates a `WHEN` written as an expression before the model reasons. It checks the routes in the order you write them. The first route that matches takes the conversation. The `PRIORITY:` field is read and then ignored, so the position of the entry sets the order.

A route with a quoted plain-language `WHEN` stays with the model. Use one as the last route for every customer that no expression matched. Set `ROLE: router` so the supervisor calls a route instead of answering in text.

A comparison on a missing value is false. If the lookup fails, no expression route matches and the model chooses the plain-language route.

You do not need to copy the tool result into session variables first. A route reads `profile.tier` directly.

## Minimal working example

This example routes on a profile lookup. It sends high-risk customers to fraud review first, then customers with an open case, then premium customers. For everyone else, including customers the lookup could not find, the model chooses the standard route.

The supervisor needs the specialist agents in the same project. The lookup tool needs an execution binding in your project, such as an HTTP endpoint. `session.customerId` is the customer identifier that the channel resolved when it authenticated the user.

```yaml expandable=true theme={null}
SUPERVISOR: Tool_Result_Routing_Supervisor
GOAL: "Look up customer state before selecting a specialist"

BEHAVIOR:
  ROLE: router

TOOLS:
  lookup_customer_profile(customer_id: string) -> {tier: string, has_open_case: boolean, fraud_risk: string}
    description: "Return customer tier, open-case status, and fraud risk for routing."
    side_effects: false
    confirm: never
    hints:
      timeout: 5000
    params:
      customer_id:
        description: "Customer identifier to look up."

ON_START:
  CALL: lookup_customer_profile
    WITH:
      customer_id: session.customerId
    AS: profile
    WHEN: session.customerId IS SET

HANDOFF:
  - TO: Fraud_Review_Agent
    WHEN: profile.fraud_risk == "high"
    RETURN: false
    SUMMARY: "Customer profile indicates high fraud risk."

  - TO: Existing_Case_Agent
    WHEN: profile.has_open_case == true
    RETURN: false
    SUMMARY: "Customer already has an open case."

  - TO: Premium_Service_Agent
    WHEN: profile.tier == "premium"
    RETURN: false
    SUMMARY: "Premium customer needs support."

  - TO: Standard_Service_Agent
    WHEN: "the customer has no fraud flag, no open case, and no premium plan, or the profile is unavailable"
    RETURN: false
    SUMMARY: "Standard customer support route."
```

These four stand-in agents let the project compile. Save each one in its own file and replace them with your real specialists.

```yaml theme={null}
AGENT: Fraud_Review_Agent
GOAL: "Review requests from customers with a high fraud risk"
```

```yaml theme={null}
AGENT: Existing_Case_Agent
GOAL: "Continue work on the customer's open case"
```

```yaml theme={null}
AGENT: Premium_Service_Agent
GOAL: "Serve premium customers"
```

```yaml theme={null}
AGENT: Standard_Service_Agent
GOAL: "Serve standard customers"
```

## How it works

* `ON_START` runs the `CALL` before the first routing check. Indent `WHEN` under `CALL`. `WHEN: session.customerId IS SET` skips the lookup for anonymous sessions.
* `AS: profile` stores the tool result. If the call fails or does not run, `profile` stays unset and all three expression routes are false.
* On each customer message, the platform checks the expression routes in order before the model reasons. The fraud route comes first, so risk wins over tier.
* `profile.has_open_case == true` matches only a boolean `true`. A tool that returns the string `"true"` does not match.
* The last route has a quoted plain-language `WHEN`. The model chooses it when no expression route matched.
* Write quoted text in plain lowercase words. The platform evaluates quoted text as an expression, not as guidance, when it contains uppercase `AND`, `OR`, or `NOT`. It does the same for a symbol such as `==` or `>`, and for the words `contains`, `matches`, `startsWith`, or `endsWith`.
* `ROLE: router` makes the supervisor call a route or ask one question. Without a `BEHAVIOR` block, the supervisor can answer in text instead.
* The specialists use `RETURN: false`, so each one keeps the conversation after the transfer.
* A `HANDOFF` entry without `HISTORY` gives the specialist the full conversation history. A project-level coordination default can change this value.
* The tool is read-only. `side_effects: false` and `confirm: never` mark it as a lookup that never asks the customer for confirmation. `hints.timeout` is a number of milliseconds. The welcome and the first routing check wait for the tool, so keep it fast.

## Common variations

### Pass the lookup result to the specialist

Add `PASS` to a route when the specialist needs the profile. The specialist receives the `profile` object.

```yaml theme={null}
HANDOFF:
  - TO: Premium_Service_Agent
    WHEN: profile.tier == "premium"
    RETURN: false
    PASS: [profile]
    SUMMARY: "Premium customer needs support."
```

A dotted name such as `profile.tier` compiles to its root field `profile`. List the root field.

### Route on remembered state

Use this variation when an earlier session or an integration stored the value. This example assumes that a `REMEMBER` rule or the memory API saved `user.loyalty_tier` for the customer.

```yaml expandable=true theme={null}
SUPERVISOR: Remembered_Tier_Supervisor
GOAL: "Route returning customers by the loyalty tier stored from earlier sessions"

MEMORY:
  PERSISTENT:
    - PATH: user.loyalty_tier
      SCOPE: user
      ACCESS: read
      TYPE: string
  RECALL:
    - ON: session:start
      ACTION: inject_context
      PATHS: [user.loyalty_tier]

HANDOFF:
  - TO: Premium_Service_Agent
    WHEN: user.loyalty_tier == "gold"
    RETURN: false
    SUMMARY: "Returning gold-tier customer needs support."

  - TO: Standard_Service_Agent
    WHEN: "the customer has no stored loyalty tier or a tier other than gold"
    RETURN: false
    SUMMARY: "Standard customer support route."
```

The route conditions have the same shape as in the lookup example. A session with no stored value, such as an anonymous or first-time customer, leaves `user.loyalty_tier` empty. The gold route is then false and the model chooses the standard route. Declare the path with `ACCESS: read` and a `RECALL` entry. Without the `RECALL`, the compiler warns with `INERT_PERSISTENT_MEMORY_DECLARATION`.

## Verification

Run one session for each outcome and inspect the trace.

1. Start as a customer with a high fraud risk. Expect `Fraud_Review_Agent`.
2. Start as a customer with an open case and a low fraud risk. Expect `Existing_Case_Agent`.
3. Start as a premium customer with no open case. Expect `Premium_Service_Agent`.
4. Start as any other customer. Expect `Standard_Service_Agent`.
5. Start anonymously, with no `session.customerId`. Expect `Standard_Service_Agent` and no lookup call.
6. Make the tool fail. Expect `Standard_Service_Agent`.

In the trace, check these events.

* `dsl_lifecycle_call_condition` shows whether the lookup ran. `tool_result` shows what the tool returned.
* `deterministic_routing` shows the matched expression route, with its `condition`, `target`, and `priority`.
* `handoff_condition_check` shows a route the model chose. Read `result`, `whenOutcome`, and `evaluatedContext` to see why the platform allowed or refused it.
* For the memory variation, `memory_init` shows that the session loaded the persistent value.

## Production readiness checklist

* The lookup tool is read-only, has a typed return that lists every field a route reads, and has a numeric `hints.timeout`.
* Each field type matches its comparison. Booleans are booleans, not strings.
* `session.customerId` comes from an authenticated channel. Use `session.identityTier` when a route must depend on a verified identity.
* Every specialist route has an owner and a short `SUMMARY`.
* A plain-language route handles every customer that no expression matched, including a failed or skipped lookup.
* `BEHAVIOR` with `ROLE: router` is set. Remove it only when the supervisor may answer some messages itself.
* The highest-risk route is first, because the entry order is the priority.
* Tests cover each route, an anonymous session, and a tool failure.
* Stored memory values have a producer, such as a `REMEMBER` rule, that you can name.

## Common mistakes

| Mistake | Why it happens | How to avoid it |
| - | - | - |
| Copying tool fields with `SET` after the `CALL` in `ON_START` | The `SET` reads as if it runs after the `CALL`. | `SET` runs before the `CALL`, so the copy is empty. Read `profile.*` in `WHEN`, or pass `profile`. |
| Using `IS SET` or `!= ""` on a dotted field such as `profile.tier` in a route | Both read as a safe presence test. | A missing dotted field passes both in a route condition. Compare to a value, such as `profile.tier == "premium"`. |
| Guarding the lookup with `session.customerId != ""` | The comparison reads as a presence test. | A missing value passes `!=`, so the call runs. Use `WHEN: session.customerId IS SET`. |
| Setting `PRIORITY:` to reorder routes | The field looks like it orders routes. | The platform ignores it. Reorder the entries. |
| Comparing a boolean field to a string | The tool returns `"true"` as text. | Declare the return field as `boolean` and return a real boolean. |
| Calling a tool that changes data to decide a route | An existing action tool is reused. | Declare a separate lookup tool with `side_effects: false` and `confirm: never`. |
| Writing uppercase `AND` or `OR` in quoted route text | It reads naturally to a person. | Use lowercase words in quoted text. |
| Passing the whole profile when the specialist needs one field | It is convenient. | Pass only what each specialist needs. |

## Troubleshooting

| Symptom | Likely cause | What to check |
| - | - | - |
| A premium customer reaches the standard route | The lookup failed or was skipped, or the field has the wrong type. | `dsl_lifecycle_call_condition`, `tool_result`, and `evaluatedContext` in `handoff_condition_check`. |
| The specialist receives an empty tier | A flat copy was made with `SET` before the `CALL` ran. | Remove the `SET`. Read `profile.tier` or pass `profile`. |
| The wrong specialist receives the customer | An earlier route is also true. | The `priority` in `deterministic_routing`. It equals the position of the entry. Reorder the entries. |
| Every anonymous session takes the standard route | `session.customerId` is missing, so the lookup is skipped. | The channel authentication and `session.identityTier`. |
| A quoted route never matches | The quoted text contains `AND`, `OR`, `NOT`, or a comparison symbol, so the platform evaluates it as an expression. | Rewrite the text in plain lowercase words. |
| The remembered tier never matches | No stored value, no user identity, or the path is not declared with `ACCESS: read`. | `memory_init`, and the `MEMORY` declaration. |


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