# Отладить работу AI-операции

> [HTML Version](ai-action-calibration.html)

Для AI‑операции в **ELMA Cortex** доступно несколько способов отладки на разных этапах её настройки и использования:

- [проверить работу AI‑операции в тестовом чате](#test-chat) — отправить входные данные и оценить результат;

- [включить трассировку AI‑операции](#tracing) — собирать данные о каждом шаге обработки запроса, чтобы оптимизировать работу AI‑операции;

- [проанализировать историю вызовов AI‑операции](#calls-list) — когда операция уже используется, можно посмотреть, как обрабатываются практические задачи в ELMA365.

Используя эти данные, вы сможете оценить, насколько работа AI‑операции соответствует вашим требованиям, а также найти причины ошибок. Затем можно скорректировать работу операции с помощью её [настроек](configure-ai-action.md): изменить инструкции, параметры генерации ответа, формат входных данных или ответа, доступные инструменты.

Чтобы использовать опции отладки, в левом меню **ELMA Cortex** перейдите на страницу **AI-Операции** и выберите нужную операцию в списке.

## Проверить работу AI-операции в тестовом чате

На вкладке **Тестовый чат** можно проверить работу AI‑операции, отправляя ей входные данные и анализируя ответы. Данные передаются в форматах, указанных в настройках AI‑операции.

Слева на странице располагается чат для отправки входных данных и отображения ответа, а справа — подробная информация об использованных инструментах. Рассмотрим, какие возможности для отладки AI‑операции доступны в тестовом чате.

### Шаг 1. Отправить входные данные в тестовый чат

Если в инструментах AI‑операции настроена авторизация по протоколу OAuth 2.0, перед работой с чатом разрешите доступ к своим данным. Для этого в нижней части вкладки нажмите появившуюся кнопку **Согласен**. Позже можно отозвать доступ, нажав справа от поля для ввода значок выхода.

После этого в левой части страницы вы сможете:

**(ai-action-calibration-1.png)**

- указывать входные данные в поле для ввода — в зависимости от формата, заданного при настройке AI‑операции, введите текст или передайте JSON‑объект.

Если при настройке AI‑операции в качестве формата задана определённая схема JSON, то значения в полях проверяются на соответствие указанным правилам. Например, если отсутствуют обязательные поля или не совпадает тип данных, вы увидите ошибку и не сможете отправить сообщение в чат;

- прикреплять файлы — для этого нажмите значок скрепки;

- указывать дополнительные источники данных — нажмите значок добавления ресурса **(cortex-resource-icon.png)**. Это позволяет задать дополнительный контекст для ответов AI‑операции:

	- **Текст** — произвольный текст, дополняющий запрос;

	- **Приложение ELMA365** — ссылка на элемент любого приложения ELMA365. AI‑операция считывает данные из его карточки;

	- **Сессия ELMA365** — ссылка на элемент приложения **Сессии** из системного раздела **Линии**;

	- **Файл ELMA365 **— ссылка на файл из раздела **Файлы** или вложение в карточке элемента в ELMA365.

- открыть окно ввода на весь экран — опция доступна, если вы передаёте данные в формате JSON. Для этого нажмите под полем для ввода значок разворачивания **(cortex-json-fullscreen-icon.png)**.

Каждое сообщение, отправленное в чат, обрабатывается отдельно. Контекст предыдущих сообщений не учитывается, так как при каждом вызове AI‑операция выполняет действия однократно на основе входных данных.

### Шаг 2. Проанализировать ответ AI-операции

После отправки сообщения в чате слева вы увидите инструменты, которые использовала AI‑операция, а также сформированный ответ. Если при настройке AI‑операции выбрана среда выполнения ReAct, отобразятся текстовые размышления, которые языковая модель выполняла между вызовами инструментов.

Если для AI‑агента настроены [проверки Guardrails](guardrails.md), вы также увидите нарушения установленных требований, зафиксированные в запросе или ответе, и обоснования решения по проверке.

Вы можете:

**(ai-action-calibration-2.png)**

1. Управлять содержимым чата с помощью кнопок:

	- **Повторить запрос** — повторно отправьте свой последний запрос на обработку, например, если произошла ошибка. Вы также можете отправить один из предыдущих запросов, нажав значок стрелки и выбрав его в списке;

	- **Очистить чат** — удалите историю запросов в тестовом чате, чтобы при обработке следующих сообщений применять обновлённые настройки AI‑операции.

2. Изучить инструменты, доступные AI‑операции, и их параметры. Для этого нажмите напротив её имени значок ящика с инструментами **(cortex-chat-tools.png)**. В открывшемся окне выберите инструмент, чтобы открыть его JSON‑схему. В ней отображаются:

**(ai-action-calibration-3.png)**

- название (код) инструмента;

- описание инструмента — текстовая инструкция с действиями, которые совершаются с помощью инструмента. По ней AI‑операция определяет, в каких случаях инструмент применяется;

- параметры инструмента — свойства, которые используются при выполнении действия, с указанием типа данных, обязательности заполнения и т. д. Например, в пользовательском наборе инструментов ELMA365 настроен инструмент, назначающий пользователям задачи. В его JSON‑схеме вы увидите поля задачи, доступные AI‑операции. Если для выполнения действия параметров недостаточно, например, отсутствуют поля для указания исполнителя и срока, перейдите к инструменту и измените его настройки.

3. Посмотреть детали вызова инструмента, нажав в чате на его текст. Тогда в правой части страницы можно:

- перейти к JSON‑схеме инструмента — для этого нажмите значок фигурных скобок **(cortex-json-schema-icon.png)**. Отобразится такая же информация, как при [просмотре схемы в списке инструментов](#tools-list);

- увидеть структуру выходных и выходных данных — чтобы скопировать её, нажмите значок планшета **(cortex-copy-icon.png).**

Если при работе AI‑операции возникла ошибка, она отображается в чате так же, как вызов инструмента, и выделяется красным цветом. Нажмите на её название, чтобы узнать подробности.

## Настроить трассировку для AI-операции

Чтобы отслеживать работу AI‑операции при обработке запроса, используйте трассировку. Вы сможете посмотреть:

- данные, которые получает и возвращает языковая модель;

- расход токенов на обработку запросов;

- факты вызова инструментов;

- данные о задержках при формировании ответов.

Трассировка AI‑операций в **ELMA Cortex** осуществляется с помощью платформы Arize Phoenix, которая располагается на отдельном сервере.

### Включить трассировку

Для использования трассировки:

1. На вкладке **Трассировка** включите опцию **Включить Arize Phoenix**.

2. Заполните появившиеся поля:

- **Адрес инстанса Phoenix** — вставьте адрес вашего сервера Arize Phoenix;

- **Идентификатор проекта** — укажите, в каком проекте в Arize Phoenix должны сохраняться трейсы по AI‑операции.

3. Нажмите **Сохранить**.

После этого трейсы для анализа можно посмотреть в указанном проекте Arize Phoenix.

### Отключить маскирование данных для трассировки

Если при создании AI‑операции вы включили [маскирование данных](masking.md), оно по умолчанию применится к текстам, которые отправляются в сервис трассировки. 

Чтобы данные анализировались в исходном виде, на вкладке **Трассировка** отключите опцию **Маскирование данных трассировки**.

## Посмотреть историю вызовов AI-операции

На вкладке **Вызовы **можно в виде списка увидеть все запуски AI‑операции:

- в [тестовом чате](#test-chat);

- из бизнес-процессов, интерфейсов и скриптов в ELMA365.

По каждому вызову в сокращённом виде отображаются входные данные и ответ, а также успешность вызова и его дата. Если для AI‑операции настроены [проверки Guardrails](guardrails.md), вы также увидите нарушения установленных требований, зафиксированные в запросах или ответах, и обоснования решений по проверкам.

Нажмите на вызов, чтобы полностью изучить входные данные, результат выполнения AI‑операции и её инструменты так же, как в тестовом чате.