Отладка инструкций
Раздел "Отладка инструкций" создан для того, чтобы помочь Вам проанализировать ответы агента, найти причины возникновения недочётов и внести корректировки для улучшения точности работы.
Когда возникает необходимость отладки
Отладка требуется в случаях, когда:
Ответ агента кажется некорректным или не соответствует ожиданиям.
Агент не вызывает функцию, хотя по логике должен это делать.
Агент вызывает функцию, но получает неожиданный результат.
Вы хотите оптимизировать работу агента, уточнив его ответы или действия.
Основные инструменты анализа:
Журнал диалогов. Позволяет анализировать историю запросов и ответов.
Продвинутый режим. Позволяет увидеть, какие функции были вызваны при ответе агента.
Экспорт диалога и анализ данных. Доступен для детального изучения логов и их анализа вне платформы.
Ниже поговорим о каждом из этих способов.
Анализ журнала диалогов
Описание журнала: Журнал диалогов в Савви предоставляет детальную историю всех взаимодействий пользователя с агентом. Он отображает вопросы пользователя, ответы агента, а также вызовы функций, если таковые были задействованы.
Шаги для анализа журнала:
Слева, на панели управления, нажмите Чаты:
Найдите нужный диалог из списка активных или завершённых и нажмите на него, чтобы открыть его журнал:
В журнале вы увидите сообщения пользователя и ответы агента.
Советы по анализу:
Если агент ответил некорректно, обратите внимание на последние несколько сообщений:
Корректно ли агент интерпретировал сообщение?
Есть ли смысловые несоответствия между вопросом и ответом?
Какие детали взаимодействия можно увидеть (например, контекст запроса)?
Не нарушен ли порядок диалога (например, агент не задал уточняющий вопрос перед выдачей ответа)?
Были ли использованы релевантные данные из контекста диалога?
Не содержал ли запрос клиента неоднозначных формулировок, которые могли быть неправильно интерпретированы.
Правильно ли агент сопоставил ключевые слова (например, название товара) сданными в базе знаний.
Если агент использует подчинённого агента, убедитесь, что запрос к подчинённому прошёл без ошибок.
Анализ вызовов функций в продвинутом режиме
Продвинутый режим позволяет пользователям видеть дополнительные технические детали внутри диалогов, включая вызовы функций, которые были выполнены агентом. Это может быть полезно для отладки и анализа корректности обработки запросов.
Как включить продвинутый режим:
Что отображается в продвинутом режиме:
Пример анализа:
На скриншоте видно, что после запроса пользователя была вызвана функция get_file_text(file=Portrait Sizes (without photos)).
Агент корректно обработал запрос и вернул ожидаемый результат.
Если вызаметили, что функция была вызвана некорректно (например, с отсутствующими или неверными параметрами), это может быть причиной некорректного ответа агента. Так же можно увидеть, правильную ли функцию вызвал агент. Проверьте, соответствует ли запрос пользователя ожидаемому формату, и уточните промпт, если это необходимо.
Если ответ агента не соответствует Вашим ожиданиям, проверьте содержимое функции:
Экспорт диалога и анализ данных
Раздел "Экспорт" предоставляет возможность сохранить всю историю диалога, включая вызовы функций, параметры и ответы, в формате веб-страницы.
Это можно сделать, нажав на кнопку экспорта в правом вернем углу выбранного диалога:
Возможности экспорта
Формат экспортируемого файла:
Экспорт производится в виде веб-страницы (.html), которая отображает всю информацию о диалоге в структурированном виде.
Содержимое экспортируемого файла :
dialogue — сюда входит информация о диалоге, данные о следующих параметрах:
_id — уникальный идентификатор диалога
сhannel_name — название канала
channel_variables — переменные канала: (type — , username — , name — , )
fields — диалоговые поля
memory — сообщения между покупателем, агентом и сотрудником, если он включился в диалог. Экспорт диалога содержит полную историю, включая фото, аудио, видео и прочие отправленные или полученные файлы.
source — источник
user — здесь находится информация о клиенте, который ведёт диалог с агентом
_id — уникальный идентификатор клиента
email — адрес электронной почты клиента
bot — объект агента, который отвечает за диалог. В нём указаны параметры:
_id — уникальный идентификатор агента
name — название агента
llm_code — название модели
test_llm_code — название тестовой модели
timezone — часовой пояс
Анализ экспорта
Результаты вызова функции
Между реплик диалога можно увидеть строку вызова функции. Она содержит название функции и переданные параметры. Например:
⚙️ Выполняется функция yc_get_available_seances_by_dates(service_ids=[13070099], dates=["2026-01-23"], staff_id=null)
Как анализировать
Название функции.
Оно указывает, какую именно задачу выполняет агент. Например,
yc_get_available_seances_by_datesиспользуется для получения доступных сеансов на указанные даты.
Переданные параметры.
staff_id– идентификатор мастера.service_id– идентификатор услуги. Указывает, какая услуга запрашивается.dates– массив дат. Показывает, для каких дат запрашивается информация.
Проблемы в параметрах
Если какой-либо из параметров передан некорректно (например, staff_id=null), агент не сможет корректно обработать запрос. В данном случае ID мастера отсутствует, что делает запрос невалидным.
Что делать при ошибке
Проверить параметры.
Убедиться, что все обязательные параметры переданы.
Например, если
staff_id=null, нужно выяснить, почему ID мастера отсутствует, и передать корректные данные.
Отладка.
Сравнить фактические параметры с ожидаемыми для данной функции.
Если агент автоматически формирует запрос, необходимо проверить логику его формирования.
Проверка и корректировка промпта.
Убедиться, что инструкции соответствуют задаче, которую должен выполнять агент.
Проверить, чтобы инструкции следовали логической последовательности
Внимательно проверить текст инструкций на наличие ошибок, подменных понятий и, особенно, противоречий.
Например, если в одной части промпта указано, что нужно искать "все доступные сеансы", а в другой – "только для одного мастера", это может привести к ошибкам.
Проверка ответа функции
Результаты вызова функции
При нажатии на информационную кнопку под функцией открывается результат выполнения этой функции.
Этот результат может быть представлен в виде:
Текста
XML-документа
Этапы анализа функций
Определение типа результата.
Если результат представлен текстом, анализируем его смысловое значение.
Если это XML-документ, проверяем структуру и данные в нем.
Проверка логики работы.
Сопоставляем ожидаемый результат функции с фактическим.
Если результат не соответствует ожиданиям, анализируем переданные параметры (видны в вызове функции).
Проверка и корректировка промпта.
Убедиться, что инструкции соответствуют задаче, которую должен выполнять агент.
Проверить, чтобы инструкции следовали логической последовательности
Внимательно проверить текст инструкций на наличие ошибок, подменных понятий и, особенно, противоречий.
Вызов таблиц
Что такое вызов таблиц? Таблицы используются для хранения структурированных данных, к которым агент может обращаться для выполнения задач. Это могут быть данные о пользователях, услугах, расписании, ценах и т.д. Подробнее о работе с таблицами можно почитать в разделе Таблицы (CSV-XLS / Google).
При обращении агента к таблице, Вы увидите функцию вида:
Если вызов таблицы не сработал или результаты некорректны, проверьте следующие моменты:
1. Отсутствие данных в таблице
Убедитесь, что таблица содержит данные, которые соответствуют запросу.
2. Не учтены параметры для поиска
Некорректный результат может быть вызван пропущенными параметрами. Обратите внимание на следующие настройки внутри таблицы:
"Поиск по части строки": если запрос ищет полное совпадение, а в таблице значение записано частично. Пример: вместо
"Москва"может быть записано"Москва, РФ"."Не учитывать регистр": если запрос чувствителен к регистру,
"москва"не найдётся вместо"Москва"."Всегда строка": Т.е. отбор на данное поле будет накладываться ни как на число, а как на строку. Пример: если мы укажем, Всегда строка, то отбор на поле "Количество > 0" не сработает, т.к. запрос предполагает поиск по числам.
3. Перегруженность таблицы
Если таблица содержит беспорядочную, неструктурированную информацию, запросы могут быть некорректны.
Симптомы: данные расположены в рандомных ячейках, строки или колонки дублируются, отсутствует логическая структура.
Решение: Проведите предварительную очистку таблицы и настройте её структуру.
4. Неверное описание таблицы
Если агент не понимает, в какой момент обращаться к таблице, проверьте:
Описание таблицы в настройках.
Логику вызова таблицы в инструкциях.
5. Ошибка в "Предварительном SQL-запросе"
Проверьте настройки таблицы:
Убедитесь, что предварительный SQL-запрос корректен и возвращает ожидаемый результат.
Пример неправильного запроса:
(Опечатка в ключевом слове
FROM).
6. Простота структуры таблицы
Для корректной работы таблица должна быть:
Без объединения ячеек.
С заполненной первой строкой (заголовками колонок).
Пример корректной таблицы:
590FV
Иванов И.
5000
591FV
Петров А.
7000
Проверка и отладка
Сравните результаты функции с ожидаемыми:
Если результат пуст, уточните SQL-запрос.
Если результат содержит ошибочные данные, проверьте настройки таблицы.
Проверьте текст инструкций:
Убедитесь, что агент точно понимает, какой запрос отправлять к таблице.
Если запрос некорректен, уточните формат команды в инструкции.
Тестируйте таблицы в изолированном режиме. Перед интеграцией убедитесь, что запросы к таблице работают без ошибок.
Обращение к подчинённому агенту
Описание: Подчинённые агенты используются для повышения качества ответов и уменьшения контекста диалога. Подробнее об этом можно почитать в разделе инструкции Мультиагентность.
Анализ в продвинутом режиме внутри диалога
Между строк внутри диалога содержатся различные элементы, которые помогают понять ход выполнения функции и взаимодействие с подчинённым агентом:
Функция вызова подчинённого агента -
invoices_search(date=, summ_usd=, summ_zl=, number_invoices=590FV).Здесь параметр590FVпередаётся для поиска информации в таблицах."Таблицы" — это название вызванного подчинённого агента.
При нажатии на кнопку "Таблицы" (название подчинённого агента), справа всплывает контекстное окно, содержащее следующую информацию:
Пройдёмся по содержимому контекстного окна:
User: отображается переданный параметр (
590FV).Результат выполнения функции: Рядом с текстом "Функция выполнена" расположена функциональная иконка
(i). При её нажатии выводится полный текст с результатами функции в формате JSON:
SQL-запрос: Функция внутри подчинённого агента:
get_price_table(sql_query=SELECT * FROM data WHERE number_invoices = '590FV')
На этапе выполнения SQL-запрос был модифицирован: $SQL запрос был заменён на SELECT * FROM data WHERE LOWER(number_invoices) LIKE '%590fv%'
Объяснение:
Запрос ищет данные в таблице (
data), фильтруя строки, где значение в поле (number_invoices) соответствует указанному параметру (590FV), без учёта регистра символов.Оператор
LIKEиспользуется для поиска подстрок, добавляя гибкость при вводе данных.
Ответ от подчинённого агента: После успешного выполнения функции подчинённый агент "Таблицы" возвращает следующий ответ:
В случае ошибки ответ будет вроде:
Здесь же мы можем заметить, что между строк не отображается оповещение о выполнении функции и SQL запроса.
Анализ экспорта диалога.
1. Данные результата вызова функции: При нажатии на иконку ℹ️ можно получить информацию о результатах выполнения функции.
Пример успешного результата:
В данном случае мы получили ответ со всеми данными, относящимися к инвойсу 590FV, из таблицы, хранящейся в подчинённом агенте.
Пример ответа при ошибке:
В данном случае мы получили запрос на предоставление более подробной информации о том, что мы ищем.
Это может быть связано с тем, что данных, которые мы запрашиваем, в таблице нет, а значит, их нет и у подчинённого агента.
2. Распознавание вызовов подчинённых агентов: В экспортируемом документе, если функция представляет собой вызов подчинённого агента, рядом с иконкой информации (i) отображается дополнительная иконка в виде головы робота 🤖. При нажатии на эту иконку откроется модальное окно:
В этом окне отображается отдельный экспорт, содержащий данные, относящиеся только к подчинённому агенту:
Т.е. функция get_price_table(sql_query=SELECT * FROM data WHERE number_invoices = '590FV') была выполнена уже внутри подчинённого агента.
Сводная информация по анализу вызова подчинённых агентов
Основные аспекты анализа:
Этапы взаимодействия:
Вызов функции подчинённого агента через основного.
Передача аргументов для выполнения запроса (например,
number_invoices=590FV).Выполнение запроса (например, SQL-запрос или get_file_text() и т.д.) и получение результата.
Отображение данных или ошибок пользователю в удобном формате (JSON, текст).
Элементы интерфейса:
Кнопка с названием подчинённого агента (например, "Таблицы").
Иконки
(i)и🤖для доступа к результатам выполнения функции.Контекстное окно с данными или сообщением об ошибке.
Анализ ошибок:
Проверка выполнения функции (оповещение "Функция выполнена" или сообщение об ошибке).
Проверка запроса на корректность.
Анализ данных, возвращаемых подчинённым агентом.
Часто встречающиеся ошибки и рекомендации по их анализу и устранению
1. Ошибка в данных (опечатка пользователя)
Описание: Пользователь вводит неверный параметр, например,
5590FVвместо590FV.Как заметить: Подчинённый агент возвращает сообщение об отсутствии данных или просит уточнить запрос. Пример:
"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"?"
Как исправить:
Проверить корректность введённых данных.
Предусмотреть логику уточнения запроса у пользователя.
2. Отсутствие данных в подчинённом агенте
Ошибка: В подчинённом агенте нет данных, соответствующих запросу.
Как заметить: В логах или интерфейсе отображается сообщение об отсутствии данных. Пример:
"No records found for the invoice number 590FV."
Как исправить:
Убедиться, что запрос корректный.
Проверить исходную базу данных подчинённого агента.
3. Общая ошибка в логике вызова
Ошибка: Вызов функции подчинённого агента выполнен неправильно (например, передача лишних или несоответствующих параметров).
Как заметить: Подчинённый агент возвращает неожиданный ответ или не выполняет функцию.
Как справляться:
Перепроверить логику работы основного и подчинённого агента.
Убедиться, что передаваемые параметры соответствуют требованиям подчинённого агента.
4. Ошибка в описании логики при вызове подчинённого агента.
Ошибка: некорректно описанная логика вызова подчинённого агента в промпте
Описание: Промпт содержит неясные или противоречивые инструкции для подчинённого агента, что приводит к ошибкам в выполнении функций. Например:
Не указано, в какой момент стоит обращаться к подчинённому агенту.
Инструкции содержат ненужные детали или лишние шаги, которые мешают агенту правильно выполнить запрос.
Как заметить:
Подчинённый агент возвращает некорректный результат или просит уточнить запрос, несмотря на наличие корректных данных. В логах или интерфейсе можно увидеть ошибки выполнения.
Главный агент вообще не вызывает подчинённого агента.
Как исправить:
Проверить промпт главного агента на наличие лишних деталей или неоднозначностей.
Проверить промпт подчинённого агента на наличие лишних деталей или неоднозначностей.
Убедиться, что логика промпта чётко описывает последовательность выполнения запроса.
Протестировать промпт с разными входными данными, чтобы убедиться, что агент понимает запрос и выполняет его правильно.
Основные советы по отладке инструкций
Эффективная отладка инструкций требует системного подхода и внимательного анализа на всех этапах взаимодействия с агентом. Чтобы быстро находить и устранять проблемы, следуйте этим рекомендациям:
Понимание необходимости отладки Начинайте с понимания, в какой момент требуется вмешательство. Если результаты работы функций или ответы агента кажутся некорректными, это сигнал для анализа.
Используйте журнал диалогов Проверьте, какие шаги выполнялись, какие параметры передавались, и какие ответы получены. Это поможет локализовать проблему на уровне диалога.
Проводите анализ вызовов функций В продвинутом режиме или с помощью экспорта изучайте запросы и результаты выполнения функций. Убедитесь, что запросы правильно сформулированы, а функции возвращают ожидаемые данные.
Работайте с экспортом диалогов Экспорт помогает более детально изучить структуру запросов, параметры вызовов и ответы агента. Используйте эти данные для диагностики и коррекции.
Проверяйте настройки Убедитесь, что в шагах диалога корректно назначены аргументы действий, а текст запроса точно передаёт логику вызова функции или подчинённого агента.
Отлаживайте взаимодействие с подчинёнными агентами Проверяйте, что промпты подчинённых агентов чётко описывают логику вызова, переданные данные соответствуют требованиям, а сами агенты настроены на работу с актуальной информацией.
Внимательно относитесь к данным Ошибки в данных или их отсутствии — частая причина некорректной работы функций. Убедитесь, что вводимые значения точны, а необходимые данные доступны в базе.
Тестируйте и анализируйте результат После внесения изменений проверяйте, как они влияют на выполнение функций и ответы агента. Постоянное тестирование помогает убедиться в стабильной работе системы.
Главный секрет успешной отладки — последовательность и внимание к деталям. Работая шаг за шагом, вы сможете быстро находить и устранять проблемы, обеспечивая надёжную работу системы.
Последнее обновление
Это было полезно?