Contents
- Instructions
- Steps and data
- Signals
- Knowledge base
- Catalog
- Reminders
- Handover to a manager and dialog ownership
- Changes and testing
This is a collection of typical agent configuration mistakes — what exactly goes wrong, why it breaks behaviour, and how to do it right. Many of these mistakes are invisible "on paper" and show up only in operation, so every change is worth checking in the test chat (see Testing and debugging).
Instructions
A poorly written main prompt. Describing the agent in a couple of lines like "You are an assistant, help clients" and expecting meaningful behaviour. Without a clear foundation, the agent does not understand who it is, what it should do, and where its boundaries are — and starts to make things up. In the main prompt it is usually worth spelling out: the agent's identity and role; the main task and work goals; general rules of communication and behaviour; key responsibilities; limitations and security requirements; a brief description of the domain (company, business); the rules for using the knowledge base and other sources. For details, see Main prompt.
An overloaded main prompt. Putting everything into one prompt — rules, branches, special cases — and hoping the agent will hold it all. The longer and more contradictory the instruction, the worse the agent follows it. Keep the main prompt short: about who the agent is and what its tasks are — and move the logic into steps, conditions, and signals.
Branching logic in words instead of mechanisms. Describing in the prompt "if the client is like this, do one thing, otherwise another" instead of assembling it with steps and conditions. The agent performs textual "if-else" unreliably. Branching — through steps and transitions with conditions, data collection — through step fields.
Conflicting rules in different slots. One slot dictates one thing, another the opposite, and the agent wavers between them. Make sure the slots complement each other rather than argue; a contradiction is usually immediately visible in the test chat from the agent's "thoughts". For details on slots, see Instructions.
Changeable data right in the prompt. Prices, deadlines, delivery terms written into the instruction have to be edited in the prompt, and they are easy to forget to update. Such data belongs in the knowledge base: the agent will retrieve it on demand, and it can be changed in one place.
Not watching the accumulated context. The saved scenario context and the temporary instructions that steps add to the agent pile up in the dashboard and strongly influence its decisions. If they are not cleared — piling on ever new directives and not removing outdated ones — the agent drowns in contradictory instructions and loses focus. This is especially insidious when the automatic context clearing on dialog closing is disabled (see Agent settings): then outdated data and directives move into the next dialog of the same chat and continue to influence the agent where they are no longer needed. Save only what is genuinely important to the context, update it in time, and remove the outdated.
Steps and data
Too many fields in one step. A step that tries to collect a dozen values at once makes the agent confused about what to ask and when. Break it into several steps by meaning.
Everything required. If you mark as required fields without which you could actually continue, the step will not finish and the agent will get stuck. Make required only what the step truly makes no sense without.
Vague names and descriptions. Fields and steps with blurry or indistinguishable names — the agent does not understand what to collect where and when the step is appropriate. Give clear, distinguishable names; add a description only where it carries real meaning rather than duplicating the name. For details, see Scenario steps.
A step always available, but unclear why. A step is visible to the agent at all times, without conditions and without a clear instruction on when to use it — and the agent calls it inappropriately. Limit its availability with visibility and conditions, or give a clear instruction on when to apply the step.
A hidden key step that cannot be returned to. The opposite extreme: an important structural step or a scenario fork is hidden right after it is passed. While the client goes strictly forward, all is well, but the moment they change their mind — change a choice, fix an answer, switch intent — the agent cannot return to the needed step, because it is already unavailable. The rule is simple: leave key steps and forks open even after they are passed, so that the agent can return to them; hide intermediate steps and transitions between branches — those needed only once — so as not to clutter the set of actions available to the agent. For details on visibility, see Scenario steps.
Signals
Signals "just in case". Each signal is separate work for the system and additional costs, and superfluous ones also add noise to the picture. Set up only the signals that steps or conditions actually depend on.
A vague signal description. A signal with a blurry description fires inappropriately. The description should be a clear instruction by which it is unambiguous when the signal is considered set.
Not accounting for the re-evaluation of a signal on every message. Signals are re-evaluated on every new message from the client, and a signal step can fire again on each new setting of the value. If repeated evaluation is not needed, say so in the signal description: re-evaluation is not required, the value is set once, and closing the dialog will reset it. If, on the contrary, the signal should be "live" and track changes in the context, that is also worth stating in the description: when the situation has changed and the signal is no longer relevant, it can be cleared. For details, see Signals.
Knowledge base
Dumping everything into one document. One huge document "about everything" searches poorly: in response to the client's query, the system returns the whole document to the agent, and along with the needed paragraph comes a pile of extraneous text that dilutes relevance and throws the agent off. Besides, such a document has one general description, from which it is hard to tell what is inside. Break the material into separate documents by topic, give clear names and descriptions, and arrange them into sections.
Not checking what was recognised from an uploaded file. The system turns files and links into text, and on complex documents — especially PDFs with tables, columns, or scans — recognition can distort the contents or lose part of it. If this text is not checked, the agent will answer from a corrupted source. After processing, open the document, look at what text was extracted from it, and fix the recognition errors manually.
Forgetting to close unanswered questions. When filling the base from unanswered questions is enabled, the agent stores the questions it did not find an answer to as "question-answer" documents in the "Moderation" status — they are not yet available to the agent, because there is no answer in them yet. If they are not reviewed and answers not added, the base does not grow, and the agent stumbles on the same questions again and again. Regularly go through the questions in moderation and close them with answers. For details, see Knowledge base.
Catalog
Counting on the agent to pull off a bad catalog. Product selection cannot be better than the catalog itself. If the structure is tangled, the products have few descriptions or no characteristics by which clients actually choose (size, colour, purpose, compatibility), the agent simply has nothing to rely on — it will suggest the wrong things or find nothing. Instructions cannot fully compensate for this. Prepare the catalog for selection: clear categories, filled-in descriptions, and the products' key characteristics; and additionally explain the specifics of the structure and the most reliable fields to the agent in the catalog instructions. For details, see Catalog subagent.
Reminders
Creating them without a cancellation plan. If you set reminders and do not think through when they will be removed, it is easy to bury the client in messages — up to complaints and the blocking of the number. Build in the cancellation conditions right away (the client replied, the conversation went down another branch, the chain ended).
Duplicating a system reminder with your own. Enabling both the system "waiting for a reply" and your own reminder for the same role — the client will get two. Choose one.
Building an aggressive chain right away. A long sequence of reminders built off the cuff more often irritates than brings the client back. Start with one or two and grow it while watching the reaction. For details, see Delayed actions.
Handover to a manager and dialog ownership
Not accounting for who the dialog is on. Configuring events as if the dialog is always on the bot. While a manager is handling the dialog, the agent does not intervene in the conversation — and steps meant to reply to the client simply will not work the way you expect. Take into account the dialog owner and the agent's start modes (see Chat events).
An event step writes to the client over the manager. A step on a timer or event sends a message even though a person has already taken the dialog — the agent butts into the manager's live conversation. Check dialog ownership before sending a message on an event.
Not accounting for the order of events at the start of a dialog. When the client writes for the first time, the events come not one by one but as a bundle, and the steps configured for them run in this order: first "Message from customer" — before the dialog is assigned to the agent; then "Dialog assignment" — the dialog moves to the agent and the agent starts; and only after that does each subsequent message come again as "Message from customer", but now with the dialog on the agent. This matters when configuring handling through event steps: the same "Message from customer" event fires the first time without an assigned dialog, and later with one. If a step on this event is meant for an already-working agent, on the first message it will behave not as you expect. For details, see Chat events.
Changes and testing
Editing the running version live. Changing behaviour right in the running version is risky: real clients will see the mistake immediately. Put changes that affect the logic through a new version (see Agent versions and statuses).
Checking once and releasing. The agent is non-deterministic: one good answer does not yet mean it will always answer that way. Run important scenarios several times before trusting the agent with real traffic (see Testing and debugging).