Documentation / Guides

Recognise what callers ask, read how they felt, and guard both sides

Define the requests your agent recognises, see how each conversation felt, and keep the safety screens.

Last updated:

Three things now happen around every conversation: the request is recognised as it is spoken and routed, the finished conversation is scored for how the caller felt and what it was about, and both what the caller says and what the agent answers pass a safety screen.

Tell the agent what people ask for#

Open an agent and go to Requests. Each entry is a name, a few examples in the words your callers actually use, and what the agent should do when it recognises that request:

  • answer from your documents, for anything your knowledge base covers,
  • run a procedure, when the request starts a flow you have defined,
  • use a tool, when it should call something,
  • offer a person, or transfer the call.

Write the examples in every language the agent answers in. The examples are what matching mostly rests on; the name and the description count too, at a much lower weight. So an entry with a good description and no examples is not switched off: it can still be recognised on the words of its description alone, and route the caller accordingly. To keep an entry stored without letting it match, switch the whole set off rather than emptying its examples.

What it does not do#

It matches the words you wrote down. It does not paraphrase, so a request phrased in vocabulary none of your examples share is not recognised, and it is not supposed to be. That is exactly what the Not yet covered list is for: every request that matched nothing is recorded there with how often it recurred and which of your entries it came closest to. A high closeness score usually means the fix is one more example on an entry you already have, which is what Add to this request does. A low one means a genuinely new kind of ask.

The match level, and tuning it from your own conversations#

Closeness is judged against a match level you can set per agent. The Not yet covered list shows the level it used and says whether you chose it or it is the platform default, because those are the same number on screen and call for opposite decisions: a default nobody picked for your callers is worth revisiting, your own considered setting usually is not. Each phrasing then shows how far it fell short of that level, so a screenful of near misses reads as one setting to adjust rather than as a hundred entries to write.

The default is deliberately cautious, and it is strict on the way people actually speak. A plain request scores well; the same request wrapped in "good morning, sorry to bother you" and "thanks" scores far lower, because every word that appears in none of your examples pulls the score down. Those requests are perfectly in scope, and at the default they land in Not yet covered rather than being routed.

We do not lower the default for you, because the right level depends on how your callers talk and nobody can know that from the outside. What the list gives you instead is the evidence: which phrasings a slightly lower level would have caught, and how much traffic they account for. Lower it one step, watch the same list, and step back if requests start matching the wrong entry. A lower level recognises more and is wrong more often; there is no setting that only does the first.

An entry you save but leave switched off costs nothing and is never matched, so you can draft a set before arming it.

See how each conversation felt#

Every finished conversation gets a reading of how the caller felt at its start and at its end, which way it moved between the two, and which of your topics it was about. This is decided once, after the call, inside the summary that already runs, so it adds nothing to what a caller waits for and nothing to what a conversation costs.

The dashboard shows the split and the trends. Two numbers are worth separating: how many conversations arrived unhappy, and how many ended unhappy. They answer different questions about the same week.

Needs review is the queue built from the conversations that both ended badly and were handed on to a person, worst ending first. It is the list to work through when you have twenty minutes rather than a day.

Emerging topics groups the themes your topic list does not cover yet. It always says how it grouped them: by meaning, or by shared vocabulary when the deployment has no semantic grouping available. Read that line before reading the clusters, because shared vocabulary is a weaker signal than shared meaning. Nothing on this screen changes how a call is answered until you add a topic yourself.

The safety screens#

Two screens run on every agent, on every plan, and you do not have to turn them on.

The input screen reads each caller turn, and each passage or tool result the agent pulls in, for attempts to talk the agent out of its instructions or to make it read them out loud. By default it records what it found and lets the conversation continue, because it matches patterns in a real person's own words and a false positive there is a broken call. On a public web widget, where the cost of a false positive is one broken chat, raising it to refuse is often the better trade. Content that came from a document or a tool is never refused: it is marked as data inside its own boundary, because dropping a passage would answer your caller with "I do not have that" over a sentence somebody wrote into a PDF.

The reply screen runs before anything is spoken or shown, on every reply the agent produces: not only its generated answers but its greeting, its farewell, its survey questions and its transfer lines. It refuses a reply that would repeat your instructions back, read out a credential, or fall into the moderation categories you left switched on. A refused reply is replaced by the agent's fallback line, in the language the caller is being served in.

The optional grounded answer check is different in kind. When an agent answers from your documents, it holds the answer back, scores it against the passages actually retrieved, and if the answer is not supported it asks the agent again under an explicit instruction to use only those passages. If that second answer still is not supported, the caller hears the fallback line instead. It costs a real pause and sometimes a whole second answer, which is why it is off unless you switch it on, and why it only ever runs on answers drawn from your documents.

What the screens do not catch#

They are pattern matching, not judgement. They catch the known shapes of "ignore your instructions", the known shapes of a leaked credential, and text that repeats your instructions almost word for word. A novel phrasing nobody has written a pattern for gets through, and so does a reply that is wrong but harmless: the reply screen is about safety, not accuracy. Accuracy is what the evaluation page, the answer ratings and the grounded answer check are for.

Every action a screen takes is counted and shown, including the times the grounded answer check could not reach a verdict and let the answer through rather than leaving your caller in silence. A guard that quietly stopped guarding would be the worst version of this feature, so that case is on the same chart as a refusal.

The console

These pages are read only. The test call, the API keys and the live API reference are in the console, where your account is signed in.

Open the console