Instruction debugging
The "Debugging Instructions" section is designed to help you analyze the bot's responses, identify the causes of errors, and make adjustments to improve the bot's accuracy.
When debugging is needed
Debugging is required when:
The bot's response appears incorrect or doesn't meet expectations.
The bot doesn't call a function, although it should logically.
The bot calls a function but gets an unexpected result.
You want to optimize the bot's performance by refining its responses or actions.
Basic analysis tools:
Dialog. Allows you to analyze the history of requests and responses.
Advanced mode. Allows you to see which functions were called during the bot's response.
Dialog export and data analysis. Available for detailed log review and analysis outside the platform.
Below, we'll discuss each of these methods.
Dialogue log analysis
Log Description: The conversation log in Savvy provides a detailed history of all user interactions with the bot. It displays the user's questions, the bot's responses, and any function calls that were made.
Steps to analyze the log:
On the left side of the control panel, click Chats:
Find the desired conversation from the list of active or completed conversations and click on it to open its log:
In the log you will see the user's messages and the bot's responses.
Analysis tips:
If the bot responded incorrectly, pay attention to the last few messages:
Did the bot interpret the message correctly?
Are there semantic inconsistencies between the question and the answer?
What interaction details can be seen (e.g., the context of the request)?
Was the conversation flow consistent (e.g., the bot failed to ask a clarifying question before providing an answer)?
Was relevant data from the conversation context used?
Did the customer's request contain ambiguous wording that could be misinterpreted?
Did the bot correctly match keywords (e.g., product name) with knowledge base data?
If the bot uses a subordinate bot, ensure that the request to the subordinate bot was successful.
Function Call Analysis in Advanced Mode
Advanced mode allows users to see additional technical details within dialogs, including function calls executed by the bot. This can be useful for debugging and analyzing the correctness of request processing.
How to enable advanced mode:
Go to the Chats section.
At the top of the interface, toggle the Advanced Mode switch. (See screenshot 1.)
What is displayed in advanced mode:
Between the lines of the dialog, you'll see blocks with information about function calls. These blocks contain:
The function name.
The arguments passed to the function.
The execution status (e.g., "Function executed successfully").
Analysis example:
The screenshot shows that the function was called after the user's request set_fields_values() .
The bot correctly processed the request and returned the expected result. If you notice that a function was called incorrectly (for example, with missing or invalid parameters), this may be the cause of the bot's incorrect response. You can also see whether the bot called the correct function. Check whether the user's request matches the expected format and clarify the prompt if necessary.
If the bot's response does not meet your expectations, check the function's contents:
Exporting dialogue and analyzing data
The "Export" section allows you to save the entire dialog history, including function calls, parameters, and responses, as a web page.
This can be done by clicking the export button in the upper right corner of the selected dialog:
Export opportunities
Export file format:
The export is produced as a web page (.html), which displays all the information about the dialog in a structured format.
Contents of the exported file:
dialogue — this includes information about the dialogue, data on the following parameters:
_id — unique dialogue identifier
channel_name — channel name
channel_variables — channel variables: (type — , username — , name — , )
fields — dialogue fields
memory — messages between the buyer, the bot, and the employee, if they are involved in the dialogue. Dialogue export contains the full history, including photos, audio, video, and other sent or received files.
source — source
user — this contains information about the client who is communicating with the bot
_id — unique client identifier
email — client email address
bot — the name of the bot responsible for the dialogue, parameters:
_id — unique bot identifier
name — bot name
llm_code — model name
test_llm_code — test model name
timezone — time zone
Export analysis
Function call results
Between dialogue lines, you can see the function call string. It contains the function name and the passed parameters. For example:
Function executing yc_get_available_seances_by_dates(service_ids=[13070069], dates=["2026-05-01"], staff_id=null)
How to analyze
Function name.
It specifies the specific task the bot performs. For example,
yc_get_available_sessions_by_datesis used to retrieve available sessions for the specified dates.
Passed parameters.
staff_id– the staff member's ID.service_id– the service ID. Indicates which service is being requested.dates– an array of dates. Indicates the dates for which information is being requested.
Problems in parameters
If any of the parameters are passed incorrectly (for example, staff_id=null), the bot will not be able to process the request correctly. In this case, the master ID is missing, making the request invalid.
What to do if an error occurs
Check the parameters.
Ensure that all required parameters are passed.
For example, if staff_id=null, you need to determine why the master ID is missing and pass the correct data.
Debugging.
Compare actual parameters with the expected ones for this function.
If the bot automatically generates a request, it is necessary to check the logic behind it.
Checking and adjusting the prompt.
Ensure that the instructions correspond to the task the bot is supposed to perform.
Check that the instructions follow a logical sequence.
Carefully review the text of the instructions for errors, misleading terms, and, especially, contradictions.
For example, if one part of the prompt specifies searching for "all available sessions," while another says "only for one master," this could lead to errors.
Checking the function response
Function Call Results
Clicking the information button below a function opens the result of that function's execution.
This result can be represented as:
Text
Example: There are no available sessions on the selected dates.
This text indicates that there are no available sessions on the selected dates.
The date and time indicate the successful return of the function call.
XML document
Example: XML document indicates that the knowledge base file was successfully retrieved and returned in the response.
Files sent successfully. Also indicates that the data was successfully sent.
Function Analysis Stages
Determine the result type.
If the result is text, analyze its semantic meaning.
If it is an XML document, check its structure and data.
Check the logic of the function.
Compare the expected result of the function with the actual one.
If the result does not meet expectations, analyze the passed parameters (visible in the function call).
Check and correct the prompt.
Ensure that the instructions correspond to the task the bot is supposed to perform.
Check that the instructions follow a logical sequence.
Carefully review the text of the instructions for errors, substitutions, and, especially, contradictions.
Calling tables
What is a table call? Tables are used to store structured data that a bot can access to perform tasks. This could include data about users, services, schedules, prices, etc. You can read more about working with tables in the Tables (CSV-XLS / Google) section.
When the bot accesses the table, you will see a function like this:
прпр
If the table call does not work or the results are incorrect, check the following:
Missing data in the table
Make sure the table contains data that matches the query.
Missing search parameters
Incorrect results may be caused by missing parameters. Pay attention to the following settings within the table:
"Search by partial string": if the query searches for an exact match, but the table contains a partial value.
Example: instead of "Moscow," "Moscow, Russian Federation" may be entered.
"Ignore case": if the query is case-sensitive, "Moscow" will not be found instead of "Moscow."
"Always string": This means that the filter for this field will be applied as a string, not a number.
Example: if we specify "Always string," then filtering for the field "Quantity > 0" will not work, since the query requires a numerical search.
Table overload
If a table contains disorganized, unstructured information, queries may be incorrect.
Symptoms: data is located in random cells, rows or columns are duplicated, and there is no logical structure.
Solution: Pre-clean the table and adjust its structure.
Incorrect table definition
If the agent doesn't understand when to access the table, check:
The table description in the settings.
The table calling logic in the instructions.
The description is a very important component, since it determines the behavior and the query that will be generated for the table.
Error in "Preliminary SQL Query"
Check the table settings:
Make sure the preliminary SQL query is correct and returns the expected result.
Example of an invalid query:
(Typo in FROM keyword).
Simplicity of table structure
For correct operation, the table must be:
Without merging cells.
With a filled first row (column headers).
Example of a correct table:
Invoice number
Client
Amount
Testing and Debugging
Compare the function results with the expected ones:
If the result is empty, refine the SQL query.
If the result contains invalid data, check the table settings.
Check the instruction text
Make sure the agent clearly understands which query to send to the table.
If the query is incorrect, clarify the command format in the instruction.
Test tables in isolation. Before integrating, ensure that queries to the table work without errors.
Subordinate Agent Interaction
Description: Subordinate agents are used to improve response quality and reduce dialogue context. More information can be found in the Multi-Agent section of the manual.
Advanced Mode Analysis within a Dialogue
Between the lines within a dialogue, various elements are contained that help understand the flow of a function and interaction with a subordinate agent:
рррррррр
The subordinate agent call function is invoices_search(date=, summ_usd=, summ_zl=, number_invoices=590FV). Here, the
590FVparameter is passed to search for information in tables."Tables" is the name of the called subordinate agent.
When you click on the "Tables" button (the name of the subordinate agent), a context window appears on the right containing the following information:
прпрпрп
Let's go through the contents of the context window:
User: The passed parameter is displayed (
590FV).Function execution result: Next to the text "Function executed" there is a function icon "" When clicked, the full text with the function results is displayed in JSON format:
рррррр
SQL query: Function inside the slave agent:
get_price_table(sql_query=SELECT * FROM data WHERE number_invoices = '590FV')At the execution stage, the SQL query was modified:
$SQL запрос был заменён на SELECT * FROM data WHERE LOWER(number_invoices) LIKE '%590fv%'
Explanation:
The query searches data in the table (data), filtering rows where the value in the field (number_invoices) matches the specified parameter (590FV), ignoring case.
The LIKE operator is used to search for substrings, adding flexibility to data entry.
Response from the subordinate agent: After successful execution of the function, the "Tables" subordinate agent returns the following response:
прпрпрп
If there is an error, the response will be something like:
прпрпрп
Here we can also notice that the notification about the execution of the function and SQL query is not displayed between the lines.
Dialog export analysis
Function call result data: Clicking the ℹ️ icon displays information about the function's execution results.
прпрпрп
Example of a successful result:
пррпрп
In this case, we received a response with all the data related to invoice 590FV from a table stored in the subordinate agent.
Example of response in case of error:
прпрп
In this case, we received a request for more detailed information about what we're looking for. This may be because the data we're requesting isn't in the table, meaning the subordinate agent doesn't have it either.
Recognizing subordinate agent calls: In the exported document, if a function is a subordinate agent call, an additional robot head icon appears next to the information icon (ℹ️). Clicking this icon opens a modal window:
прппр
This window displays a separate export containing data specific to the slave agent:
That is, the function get_price_table(sql_query=SELECT * FROM data WHERE number_invoices = '590FV') was already executed inside the subordinate agent.
Summary of Subordinate Agent Call Analysis
Key aspects of analysis:
Interaction stages:
Calling a subordinate agent function through the master agent.
Passing arguments to execute the query (e.g., number_invoices=590FV).
Executing the query (e.g., an SQL query or get_file_text(), etc.) and retrieving the result.
Displaying data or errors to the user in a convenient format (JSON, text).
Interface elements:
A button with the subordinate agent's name (e.g., "Tables").
A "ℹ️" or "" icon for accessing the function execution results.
A context window with data or an error message.
Error analysis:
Verifying function execution (notification "Function completed" or an error message).
Checking the query for correctness.
Analysis of the data returned by the subordinate agent.
Common errors and recommendations for their analysis and elimination
1) Data error (user typo)
прпрп
прпрп
Description: The user enters an invalid parameter, for example, 5590FV instead of 590FV.
How to detect: The subordinate agent returns a message about missing data or asks to clarify the request. Example:
"Please provide more details about what you are looking for. Are you searching for a specific date, transaction amount, or invoice number related to "5590FV"?"
How to fix:
Check the accuracy of the entered data.
Develop a logic for clarifying the user's request.
2) Missing data in the subordinate agent
Error: The slave agent has no data matching the request.
How to notice: A message about missing data is displayed in the logs or interface. Example:
"No records found for the invoice number 590FV."
How to fix:
Make sure the request is correct.
Check the slave agent's source database.
3) General error in calling logic
Error: The call to the slave agent function was executed incorrectly (for example, passing unnecessary or inappropriate parameters).
How to detect: The slave agent returns an unexpected response or fails to execute the function.
How to resolve:
Recheck the logic of the master and slave agents.
Ensure that the passed parameters meet the requirements of the slave agent.
4) Error in logic description when calling a subordinate agent
Error: Incorrectly described subordinate agent invocation logic in the prompt
Description: The prompt contains unclear or contradictory instructions for the subordinate agent, leading to errors in function execution. For example:
The time to call the subordinate agent is not specified.
The instructions contain unnecessary details or extra steps that prevent the agent from correctly executing the request.
How to spot:
The slave agent returns an incorrect result or requests further refinement despite having valid data. Execution errors may be visible in the logs or interface.
The master agent does not call the slave agent at all.
How to fix:
Check the master agent's prompt for unnecessary details or ambiguities.
Check the slave agent's prompt for unnecessary details or ambiguities.
Ensure that the prompt logic clearly describes the request execution sequence.
Test the prompt with different inputs to ensure the agent understands the request and executes it correctly.
Basic Tips for Debugging Statements
Effective statement debugging requires a systematic approach and careful analysis at all stages of interaction with the agent. To quickly find and fix problems, follow these guidelines:
Understand the Need for Debugging Start by understanding when intervention is required. If function results or agent responses appear incorrect, this is a signal for analysis.
Use the Conversation Log Check what steps were performed, what parameters were passed, and what responses were received. This will help isolate the problem at the conversation level.
Analyze Function Calls Using Advanced Mode or using Export, examine requests and function execution results. Ensure that requests are correctly formulated and that functions return the expected data.
Work with Conversation Exports Exports help you examine request structure, call parameters, and agent responses in more detail. Use this data for diagnostics and correction.
Check settings Ensure that dialog steps correctly assign action arguments, and that the request text accurately conveys the logic for calling a function or subordinate agent.
Debug interactions with subordinate agents Ensure that subordinate agent prompts clearly describe the call logic, the transmitted data meets requirements, and the agents themselves are configured to work with up-to-date information.
Be careful with data Data errors or missing data are a common cause of incorrect function operation. Ensure that input values are accurate and the necessary data is available in the database.
Test and analyze the results After making changes, check how they affect function execution and agent responses. Ongoing testing helps ensure the system is functioning reliably.
The key to successful debugging is consistency and attention to detail. Working step by step, you'll be able to quickly identify and fix issues, ensuring reliable system operation.
Last updated