Agent instructions

Copy the link to the article

Copied

Contents

1. Distributed instructions
   • Overview of instruction channels
2. Main prompt
   • Recommended structure
   • What to place in the main prompt
   • What is better moved to other mechanisms
   • Practical recommendations
3. Additional prompt slots
   • When slots are used
   • How slots work
   • How to use each slot
4. Scenario instructions
   • Scenario step instructions
   • Two-way highlighting
   • The Add instruction action
   • Transition instructions in the Go to another step action
   • Persistent context via the Update scenario context action
   • Comparison of scenario instructions
5. Work dashboard
6. Signals
7. Descriptions of scenario step variables
8. How to write instructions
   • Use clear and specific wording
   • Describe the desired behaviour
   • Explain the reason for the rule
   • Separate instructions by topic
   • Place instructions in the right location
   • Avoid contradictions
   • Start with simple instructions
   • Define behaviour when there is no answer
   • Choose the right language for instructions
9. Symptoms and where to look for causes
   • Iterative approach

Instructions are the main way to control the agent's behaviour. The main prompt is only one of the places where instructions can be: the agent also receives them through prompt slots, knowledge base search, and the work scenario.

This document describes the architecture of the agent's instructions: which channels exist, at which stages of work they are used, how long they last, and which types of rules are best placed in each of them. A correct distribution of instructions helps keep the agent's behaviour predictable and makes its configuration easier to maintain as its complexity grows.

Distributed instructions

Instructions should be distributed by purpose, visibility, and lifetime. If one channel is overloaded — especially the main prompt — the agent loses focus, gets stuck in wordy instructions, and ignores details. Each rule should stand out exactly where it matters most.

The influence of an instruction depends on four things: where it is placed within the agent's total volume of instructions, when it becomes visible, how close it is to the current moment of the dialog, and how long it stays active.

You should not put all instructions in the main prompt. General working rules, the agent's positioning, and security requirements really do belong there; however, instructions tied to specific tasks or context are better placed closer to where they are used. The closer an instruction is to the moment of carrying out the task, the more specific and action-oriented it can be.

Overview of instruction channels

Main prompt

The main prompt is the primary source of the agent's permanent instructions. It defines its role, tasks, general behaviour rules, and boundaries of responsibility. Unlike scenario steps, signals, and temporary instructions, the main prompt is present in the agent's work permanently and influences all dialogs.

The main prompt is best suited for information that must remain valid regardless of the current scenario, the dialog stage, or the client's state.

Recommended structure

The structure can vary depending on the agent's task, but it is usually useful to follow this order:

1. The agent's identity and role
2. The main task and work goals
3. General rules of communication and behaviour
4. The agent's main responsibilities
5. Limitations and security requirements
6. A brief description of the domain
7. Rules for using the knowledge base and other sources of information

Using headings and logical sections makes instructions easier to maintain and helps avoid contradictions as the agent's configuration grows.

What to place in the main prompt

The main prompt is especially well suited for the following types of information:

• the agent's role and positioning;
• a description of the company or business;
• the agent's main tasks;
• the rules for communicating with clients;
• general requirements for the quality of replies;
• limitations and security rules;
• a description of the available knowledge sources;
• general principles for using scenarios and tools.

Such instructions rarely change during the agent's work and should apply equally in all dialogs.

What is better moved to other mechanisms

The main prompt is not meant to hold all of the agent's working logic.

The following types of information are usually better placed in other components of the system:

• detailed descriptions of products and services, frequent questions and answers — in the knowledge base;
• multi-stage processes and sequences of actions — in scenarios;
• temporary instructions for the current stage of work — the Add instruction action;
• transitions between scenario stages — the Go to another step action;
• long-lived dialog context — the Update scenario context action;
• automatic detection of states and conditions — via signals.

This separation keeps the main prompt compact and focused on the agent's permanent working rules.

Practical recommendations

It is best to view the main prompt as a description of the agent's personality, responsibilities, and general working principles, not as a place to store all of the system's possible instructions.

If a particular rule applies only to a specific scenario, a client state, or a dialog stage, there is usually a more suitable mechanism than adding that rule to the main prompt.

For especially important rules, duplicating instructions in several places is acceptable. For example, a key requirement can be stated both in the main prompt and in the instruction of the corresponding scenario step.

Additional prompt slots

Besides the main prompt, the agent can receive additional instructions through specialised slots. Each slot is meant for a particular type of context and is activated only when the corresponding conditions are met.

This separation lets you keep instructions next to their area of application and avoid overloading the main prompt with rules that are only needed in specific situations.

When slots are used

How slots work

The Main prompt slot is the primary source of permanent instructions and has the strongest influence on the agent's general behaviour. This is usually where the agent's role, tasks, limitations, and general communication rules are placed.

The Knowledge base and Response format slots are available to the agent at all times. They let you supplement the built-in mechanisms for working with the knowledge base and formatting replies with your own instructions.

The Working hours, Non-working hours, and Client information slots are activated only when they are added in the agent settings.

The slots related to the product catalog are used only when catalog work is enabled. The Work with catalog slot configures the main agent's interaction with the catalog subagent, while the Product catalog slot configures the work of the subagent itself, which is responsible for searching for products, selecting items, and assembling the order cart.

How to use each slot

Main prompt

The agent's main slot. Contains its role, tasks, limitations, and general behaviour rules.

This slot is used in all dialogs and has the strongest influence on the agent's general behaviour. This is where it is recommended to describe the agent's identity, its responsibilities, communication rules, and other instructions that must apply regardless of the scenario, the time of day, or the client's state.

Detailed recommendations for configuring the main prompt are in the Main prompt section.

Working hours / Non-working hours

Slots for configuring the agent's behaviour depending on working hours.

At any given moment, the agent receives only one of these slots: the one for working hours or the one for outside them. Which slot is used is determined by the schedule configured in the system. If the corresponding slot is not filled, no additional instructions are added.

These slots are suitable for rules that should change depending on the availability of staff or the company's internal processes. For example:

• whether the dialog can be handed over to a manager;
• whether the client should be told about working hours;
• whether contact details should be collected for a callback;
• whether reminders or tasks can be created for the next working day;
• what expectations about response times need to be communicated to the client.

It is recommended to use such slots when the agent works around the clock but its behaviour must take the company's schedule into account.

Knowledge base

This slot is meant for configuring the agent's work with the knowledge base.

The system automatically provides the agent with information about the available documents and the mechanisms for searching them. The customisable part of the slot lets you additionally explain the structure of the knowledge base and the specifics of the domain.

Here it is recommended to describe:

• the most important documents;
• the company's internal terms and abbreviations;
• the names of products, services, and processes;
• the correspondence between clients' wordings and the documentation's terminology;
• the documents that should be considered the primary source of information on particular topics.

This slot is especially useful when clients use one terminology and the company's documentation uses another. A well-configured slot helps the agent link clients' questions to the right sections of the knowledge base and improves the quality of information search.

Response format

This slot is meant for configuring the style and formatting of the agent's replies.

The basic communication parameters are set through the agent settings: language, tone of communication, reply length, and message-splitting rules. This slot lets you additionally refine the formatting requirements for replies.

In this slot you can describe:

• the preferred communication style;
• the acceptable level of formality;
• the use of emoji;
• the formatting of lists and structured replies;
• the specifics of wording when confirming, refusing, or handing the dialog over to an employee;
• any other requirements for the appearance of messages.

It is recommended to use this slot for reply formatting rules, not for business logic or work scenarios.

Work with catalog

This slot is used only when working with the product or service catalog is enabled.

It is meant for configuring the main agent's interaction with the specialised catalog subagent. Through this slot you can explain in which situations the catalog should be used and which tasks should be delegated to the subagent.

Here you can place instructions about:

• when products or services should be searched for in the catalog;
• which types of requests require using the catalog;
• which specifics of the catalog are important to take into account;
• how the agent should act when selecting products or assembling the cart.

If the main agent does not always use the catalog correctly or misses situations where a product search should have been performed, additional instructions should usually be added precisely to this slot.

Product catalog

This slot is meant for configuring the catalog subagent itself.

The subagent is responsible for searching for products and services, selecting suitable options, and assembling the cart for subsequently creating an order. This slot lets you adapt its work to the specifics of a particular business and the catalog structure.

Here it is recommended to describe:

• which product fields and properties are the most reliable;
• which categories and attributes should be taken into account in the search;
• the specifics of the catalog structure;
• the rules for working with stock and product availability;
• additional criteria for filtering results.

This slot is especially useful for catalogs with a complex structure, non-standard product names, or incompletely filled-in cards.

Client information

This slot is meant for configuring the agent's work with the client's CRM data.

When activated, the agent receives a brief summary of the client that may include their name, contact details, address, tags, and the values of custom CRM fields.

The customisable part of the slot determines how the agent should use this information during communication.

For example, here you can describe:

• which information should be used in the greeting to the client;
• which client tags the agent should pay attention to;
• which client data is especially important for the agent's work;
• which data should be ignored in certain situations.

It is recommended to use this slot for rules on interpreting CRM data, not for storing the client's data itself.

Scenario instructions

The scenario provides several types of instructions that influence the agent's behaviour at different stages of work. They differ in the moment they appear in the agent's context, the duration of their effect, and the tasks they are meant for.

When designing a scenario, it is important to understand this difference and use each mechanism for its purpose. This makes the agent's behaviour more predictable and avoids overloading individual instruction channels.

Scenario step instructions

A step instruction explains to the agent the purpose of the scenario step, the conditions for its use, and the data that needs to be obtained to run it.

Such instructions are available to the agent before the step is called and help it navigate the available scenario options. The agent uses them to decide which step is suitable for the current situation and what data needs to be collected from the client.

It is recommended to use step instructions to answer the following questions:

• what this step is for;
• in which situations it should be called;
• what data needs to be obtained before running it;
• what actions are expected of the agent at the scenario level.

A step instruction should not describe the internal implementation of the system's actions. The agent works with the scenario at the level of steps and does not know which actions are performed inside a step after it runs successfully.

If a step is an important entry point into the scenario, this should be stated explicitly in its description.

Two-way highlighting

For especially important actions, it is useful to use several instruction channels at once.

For example, the existence of an important step can be mentioned in the agent's main prompt and additionally described in detail in the step's own instruction. This approach reduces the likelihood that the agent will skip the necessary functionality while working with the scenario.

The Add instruction action

Add instruction is meant for adding temporary instructions after a scenario step runs.

Unlike the step instruction, which helps decide whether to call the step, Add instruction influences what the agent should do next after finishing the current stage.

Usually such instructions are used for:

• clarifying questions to the client;
• explaining the next actions;
• carrying out a specific task after finishing the step;
• passing additional context between scenario stages.

Instructions of this type should be short, specific, and oriented towards the agent's immediate actions.

Transition instructions in the Go to another step action

Go to another step is used to manage transitions between scenario steps.

After a step runs, the agent receives information about the next recommended step and can receive additional explanations about the reasons for that transition.

If Add instruction answers the question "what to do next", Go to another step answers "where to move next within the scenario".

This mechanism is especially useful in multi-stage scenarios, where the order of running the steps matters and must be controlled by the system.

Persistent context via the Update scenario context action

Update scenario context lets you save important information in the work dashboard and make it available to the agent at later stages of work.

Unlike temporary instructions, this context is preserved between scenario steps and continues to influence the agent's behaviour until it is changed or removed.

This mechanism is convenient for storing:

• the parameters chosen by the client;
• important agreements;
• intermediate scenario results;
• the client's limitations and preferences;
• information that will be needed at the next stages of work.

Since such context is preserved for a long time, it is recommended to store only genuinely important information in it and to clear outdated data in good time.

Comparison of scenario instructions

The step instruction helps the agent understand the purpose of the available steps and choose the appropriate action according to the configured scenario.

The Add instruction action is used to pass a specific task that needs to be performed right after finishing the current step.

The Go to another step action manages transitions between scenario steps and helps the agent move along a predefined logic.

The Update scenario context action serves to store important information between scenario stages and forms the agent's long-term memory within the current work process.

Used together, these mechanisms let you separate permanent rules, current tasks, scenario navigation, and long-term context, without overloading a single instruction source with all possible requirements.

Work dashboard

The work dashboard is a dynamic summary of the agent's current state. Unlike prompt slots and the knowledge base, the dashboard contains information relevant to running the current scenario and is updated regularly during work.

The dashboard can contain:

• the current date and time in the CRM's time zone
• the active signals and their values
• the context saved via the Update scenario context action
• the current scenario tasks
• the filled-in and missing field values
• the temporary instructions added via the Add instruction action
• the active transitions between scenario steps

The dashboard significantly influences the agent's behaviour, since it contains the most up-to-date operational context. It is based on this information that the agent makes decisions about its next actions and about running the scenario.

It is recommended to keep the dashboard's contents up to date and to avoid accumulating outdated tasks, instructions, and transitions. Excessive or contradictory context can negatively affect the quality of the agent's decisions.

Special attention should be paid to the use of the Update scenario context action. Context saved this way can remain available to the agent for a long time and continue to influence its behaviour even after the original task is finished. For long-lived context, it is recommended to save only genuinely important information and to update or remove outdated data in good time.

Signals

Signals are background mechanisms for analysing the conversation that allow certain states, events, or patterns of the client's behaviour to be detected automatically.

When triggered, a signal becomes available to the agent through the dashboard and can influence its further decisions. In addition, a signal can trigger hidden scenario steps, perform system actions, and add temporary instructions to change the agent's behaviour.

Signals are convenient for automatically detecting states that are difficult or undesirable to describe directly in the agent's instructions: for example, signs of client dissatisfaction, repeated refusals, potentially problematic situations, signs of a valuable lead, or conditions for modifying the standard work scenario.

Detailed recommendations for designing and configuring signals are in the Signals section.

Descriptions of scenario step variables

A detailed description of the structure of scenario steps, fields, and options is in the Scenario steps section.

It is important to bear in mind that the descriptions of scenario step fields and available options, as well as the rules for requesting required data, are also part of the agent's instruction system. They help it understand what data needs to be obtained from the client, how to fill in scenario step fields, and by what criteria to choose between the available options.

The more precise and specific the descriptions of fields and options are, the more stably the agent collects data and makes decisions while running the scenario.

How to write instructions

Use clear and specific wording

An instruction should describe the agent's expected behaviour as unambiguously as possible. The more specific the rule, the more stably it will be followed.

Bad: "Be helpful and reply well"

Good: "If the client's question needs clarification, ask one clarifying question. After that, give a specific answer and suggest the next step."

Describe the desired behaviour

Whenever possible, phrase instructions in terms of the expected result rather than a list of prohibitions.

Bad: "Do not use markdown"

Good: "Reply in plain text, without formatting"

The exception is security restrictions and other rules that must not be broken.

Explain the reason for the rule

If a rule is related to the specifics of the business, client service, or the company's internal requirements, it is useful to briefly explain the reason.

Bad: "Do not mention the weight of dishes"

Good: "Do not mention the weight of dishes. Clients choose dishes by their composition and taste, and exact values can create the wrong expectations."

Understanding the reason helps the agent apply the rule in similar situations.

Separate instructions by topic

Use headings and logical blocks for the different aspects of the agent's behaviour. Do not mix the description of the agent's role, communication rules, business logic, and reply examples in one section.

Well-structured instructions are easier to maintain and develop as the scenario grows.

Place instructions in the right location

Not all rules should be in the main prompt. General working principles and the agent's role are usually located in the main instructions, while rules relating to specific tasks or context are better placed closer to where they are applied: in prompt slots, scenario steps, signals, or the knowledge base.

Avoid contradictions

Different instruction sources should complement one another, not conflict.

If special rules exist for particular situations, it is recommended to explicitly define their priority relative to the general instructions.

Start with simple instructions

In many cases, clear rules and a description of the work process are enough for the agent. Additional behaviour examples should be added only when simple instructions are not enough to get a stable result.

Define behaviour when there is no answer

It is important to define in advance how the agent should act in situations where the necessary information is missing.

Example: "If the answer is not in the knowledge base, tell the client and offer to hand the dialog over to an employee. Do not make up information about products, prices, deadlines, or service conditions."

Choose the right language for instructions

Instructions related to communication with the client should be written in the language of the target audience. Questions to the client, reply templates, and message examples should also match the language of communication.

Technical field descriptions, validation rules, and service comments can use the language adopted during the system configuration.

Symptoms and where to look for causes

Iterative approach

It is recommended to start configuring the agent with the minimum necessary set of instructions: the main prompt, the needed slots, the knowledge base documents, and the scenario steps. After testing on real dialogs, changes should be made in the channel that most closely matches the detected problem.

Not all problems should be solved through the main prompt. Different mechanisms are meant for different tasks: field descriptions for extracting data, scenario steps for controlling behaviour, Update scenario context for long-lived context, signals for automatically detecting states, and the knowledge base for reference information.

After each change, it is important to check for duplicated instructions, contradictions between the different configuration channels, and the impact of the changes on the agent's other work scenarios.