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:- Exact match. The comparison ignores case unless
case_sensitive: true. The runtime stores the table’s spelling and does not ask. “heathrow” becomes “Heathrow”. - Fuzzy match, if
fuzzy_match: true. It scores the value against every entry, ignoring case. The score is1 - (edits ÷ length of the longer string). The best entry at or abovefuzzy_thresholdis the suggestion. - No match. The runtime drops the value and tells the customer the value is not valid. The field stays missing.
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.agents/trip-destination-intake.agent.abl
destinationis aGATHERfield. The customer supplies it, and thedestinationstable checks it.destinationsis a project-local resource. The agent does not define it.
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.
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
destinationis aGATHERfield checked against the project tabledestinations.
Choose where the list lives
Setsource 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 ownLOOKUP_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.
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
profile_namecomes from the caller data your channel passes at session start, read assession.profile_name. This is a project-local assumption. Your integration must set it.spoken_nameandsecond_attemptareGATHERfields. The caller supplies them.
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_requestedlists the suggested value and score for each field.lookup_fuzzy_confirmation_interactionshows the decision: accept, decline, or unresolved.lookup_fuzzy_acceptedandlookup_fuzzy_rejectedshow the outcome.lookup_validation_failedlists 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
collectiontable 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.