Skip to main content
Back to how-to guides Use a lookup table with fuzzy matching to accept a misspelled value, such as “Heathrw”, when the correct values come from a list you own. The agent asks the customer to confirm the closest entry before it stores it.

Concept

ABL does not match fuzzily by default. Most fields compare exact text. Fuzzy matching exists in two places only. These features do not match fuzzily: A lookup table is a good fit for a list you control, such as airports, branches, or product names. For a short, fixed list of choices, use an enum and add the common misspellings as synonyms. See Validate fields with enums and allowed values.

How a lookup table decides

For each collected value, the runtime does this in order:
  1. Exact match. The comparison ignores case unless case_sensitive: true. The runtime stores the table’s spelling and does not ask. “heathrow” becomes “Heathrow”.
  2. Fuzzy match, if fuzzy_match: true. It scores the value against every entry, ignoring case. The score is 1 - (edits ÷ length of the longer string). The best entry at or above fuzzy_threshold is the suggestion.
  3. No match. The runtime drops the value and tells the customer the value is not valid. The field stays missing.
A suggestion is never stored on its own. The agent asks, and the customer decides. Short values score low. One missing letter in a three-letter code drops the score to 0.67. Do not use fuzzy matching for short codes.

Minimal working example

A flight agent accepts one of five airports. It asks for confirmation when the customer misspells one. First, create the table once for the project. Add it in the project’s runtime configuration, in the Lookup Tables section. This fragment shows the settings. It is not ABL.
Then link the field to the table. agents/trip-destination-intake.agent.abl
Variable sources:
  • destination is a GATHER field. The customer supplies it, and the destinations table checks it.
  • destinations is a project-local resource. The agent does not define it.
If the table does not exist, nothing warns you and nothing is checked. See Common mistakes.

How it works

Where the check runs decides how the customer hears about a near match. In a FLOW step, the customer’s reply to “Did you mean” is read as follows:
  • Accept (such as “yes”): the runtime stores the suggestion.
  • Decline (such as “no”): the runtime clears the field and asks again. A reply such as “no, Gatwick” is read as the new answer.
  • Unclear: the runtime repeats the question and keeps the suggestion.
The “Did you mean” and “not a valid value” wording is fixed English text. You cannot override it with MESSAGES. A field with sensitive: true never gets a suggestion. A near match counts as no match, and the message does not quote the value. This stops the agent from revealing a valid value.

Common variations

Top-level GATHER

The same table works with a model-led agent. The model asks the confirming question. agents/trip-destination-global.agent.abl
Variable sources:
  • destination is a GATHER field checked against the project table destinations.

Choose where the list lives

Set source on the table. The fuzzy settings work for two of the three sources. An api table sends the value to your endpoint and trusts the answer. The endpoint returns found and matched_value. The runtime computes no score, so it never asks “Did you mean”. If your endpoint corrects a spelling, the runtime applies the corrected value silently. See Validate values using an external lookup API. The lookup settings in a project table:

Agent-local tables

An agent can declare its own LOOKUP_TABLES: block. The compiler reports warning AGENT_LOOKUP_TABLE_EXPERIMENTAL: agent-local tables are experimental and not shared with other agents. Prefer the project table. This is a section snippet. It keeps the table next to the agent.
Write an endpoint: URL without quotes. A quoted URL is read with the quotes and fails with E485. A project table and an agent table cannot share a name. The runtime raises a conflict error.

Verify a spoken name, email, address, or number

Lookup tables compare against a list. To compare what a caller said with one stored value, use the match functions in a condition. They are built for speech-to-text output. kind is "name", "email", "address", "phone", "digits", "text", or "auto". "auto" picks a kind from the stored value. You do not set a threshold. The platform sets the bands: 70 and above is a match, 50 to 69 is a near miss worth a retry, and below 50 is a mismatch. For phone and digits, every digit must match. A missing or empty value returns "missing", and MATCH_SCORE returns -1. A score of -1 is below every threshold, so a rule such as MATCH_SCORE(...) >= 70 fails closed. agents/caller-verification.agent.abl
Variable sources:
  • profile_name comes from the caller data your channel passes at session start, read as session.profile_name. This is a project-local assumption. Your integration must set it.
  • spoken_name and second_attempt are GATHER fields. The caller supplies them.
The retry branch gives one more attempt. A second near miss is refused.

Verification

Test the lookup example with these replies. Send them in a test session and open the session trace. For the caller check, set profile_name to “John Smith” and test “Jon Smyth” (verified), “Katherine Johnson” against “Katherine Johnston” (one retry), and “Mark Lee” against “Mary Lee” (refused). Trace events to check:
  • lookup_fuzzy_confirmation_requested lists the suggested value and score for each field.
  • lookup_fuzzy_confirmation_interaction shows the decision: accept, decline, or unresolved.
  • lookup_fuzzy_accepted and lookup_fuzzy_rejected show the outcome.
  • lookup_validation_failed lists values that matched nothing.

Production readiness checklist

  • The table exists in the project before you publish the agent. A missing table disables the check without a warning.
  • The threshold is tested with real misspellings from your customers. Start at 0.8, and check both a near match and a clear miss.
  • Fuzzy matching is off for short codes and for identifiers where a wrong guess has a cost.
  • A collection table has 500 rows or fewer, or you accept that later rows are not scored.
  • Fields that hold secrets set sensitive: true.
  • Customers have a way out when nothing matches. The agent otherwise asks again.
  • Identity checks route a "mismatch" result to a refusal or a human. They never fall through to account details.
  • profile_name, or any stored value you compare against, is set by your integration before the first turn.

Common mistakes

Troubleshooting