# Отладить работу AI-агента

> [HTML Version](cortex-agent-calibration.html)

В **ELMA Cortex** доступны различные способы отладки AI‑агента. Вы можете:

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

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

- когда агент уже используется в ELMA365 — [посмотреть историю переписки с AI‑агентом в тредах](#threads). 

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

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

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

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

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

### Отправка запросов в тестовый чат

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

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

**(cortex-ai-agent-calibration-1.png)**

- писать сообщения в поле для ввода;

- прикреплять файлы, нажав значок скрепки;

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

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

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

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

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

### Работа с ответами AI-агента

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

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

В чате вы можете:

**(cortex-ai-agent-calibration-2.png)**

1. Нажать кнопку **Очистить чат**, чтобы начать диалог заново. Это позволяет применить обновлённые настройки AI‑агента, а также не учитывать контекст предыдущей переписки при проверке нового запроса.

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

**(cortex-ai-agent-calibration-3.png)**

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Посмотреть историю взаимодействия с AI-агентом в тредах

На вкладке **Треды **в виде списка** **отображаются:

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

- диалоги пользователей с AI‑агентом в ELMA365 — позволяют проанализировать практическое применение агента.

В таблице вы увидите название треда и дату начала переписки. Нажав на тред, вы можете посмотреть содержание диалога и использованные инструменты так же, как в [тестовом чате](#tools-info). Если для AI‑агента настроены [проверки Guardrails](guardrails.md), вы также увидите нарушения установленных требований, зафиксированные в запросах или ответах, и обоснования решений по проверкам.

Когда AI‑агент отлажен и готов к работе, [сделайте его доступным для пользователей](cortex-agent-access.md).