Skip to content

Common issues

Quick diagnosis

Start with the symptom, then check the most likely area: prompt, memory, routing, forwarding, tools, knowledge, or voice. Avoid changing everything at once.

The goal is a small fix backed by evidence.

Work from the symptom to the likely cause: identify what went wrong, check the most relevant area, then change one thing and test again.

The agent ignores my prompt

Check:

  • Is the instruction specific and testable?
  • Is it hidden in a long paragraph?
  • Does another instruction conflict with it?
  • Is the agent missing required information?
  • Are you expecting a parameter change to fix a prompt issue?

Fix:

  1. Rewrite the instruction as a short bullet.
  2. Add the condition when it applies.
  3. Add the fallback behavior.
  4. Test the same scenario again.

The agent invents information

Check:

  • Does the prompt say what to do when the answer is unknown?
  • Is the knowledge base connected and up to date?
  • Is the user asking for information that is not in the knowledge base?

Fix:

Add a boundary such as:

If the answer is not available in the knowledge base, say that you are not sure
and offer to collect the caller's details for follow-up.

Routing does not happen at the expected time

Check:

  • Is the phone number assigned to the right default route?
  • Is the routing override enabled?
  • Is the routing timezone correct?
  • Do the days and times match the expected window?
  • Does the time window cross midnight?
  • Is another override overlapping?

Forwarding does not work

Check:

  • Is the forwarding tool available to the agent?
  • Does the prompt tell the agent when to use it?
  • Does the target name match the configured forwarding target?
  • Is the phone number in E.164 format?
  • Is the timeout long enough?
  • Is call screening enabled when the recipient expects direct forwarding, or the other way around?

The agent uses a tool too early

Check whether the prompt requires confirmation and required information before tool use.

Example fix:

Only send an SMS after the caller has agreed to receive it.
Before sending, repeat the phone number and ask for confirmation.

The voice sounds wrong

Check:

  • selected voice,
  • language/accent,
  • expressiveness,
  • speech tempo,
  • speaking style availability.

If the content is wrong, fix the prompt or knowledge base first. Voice settings only change how the agent sounds.