Как создать ИИ-агента: пошаговый разбор на реальном кейсе

Абстрактные схемы плохо переносятся в код. Разберём одну конкретную задачу целиком - включая то, что в итоге не стало агентом.

Кейс и требования

Задача: входящие обращения в свободной форме нужно превращать в тикеты с заполненными полями. Обращения приходят из разных каналов, пишут их люди, а не формы: с опечатками, без структуры, иногда несколько вопросов в одном сообщении.

Требования, сформулированные до начала:

• Определить категорию из фиксированного списка.
• Проставить приоритет по понятным правилам.
• Найти клиента в базе, если он там есть.
• Создать тикет.
• Если уверенности нет - отдать человеку, а не угадывать. Это требование важнее остальных.

Критерий готовности: создан тикет с заполненными обязательными полями либо обращение помечено как требующее человека. Проверяется программой.

Схема

Первый вопрос - нужен ли здесь агент. Ответ: частично.

• Разбор текста - это один вызов модели со схемой ответа. Не агент.
• Поиск клиента - это запрос в базу. Не агент, обычный код.
• Приоритет по правилам - это условия. Не агент.
• Уточнение при неоднозначности - вот здесь появляется цикл: модель может понять, что данных не хватает, запросить дополнительную информацию из базы и пересмотреть решение.

Итоговая пропорция: агентная часть занимает примерно четверть системы. Остальное - код. Это не компромисс, а нормальная архитектура; попытка сделать агентом всё даёт систему, которая в три раза дороже и втрое хуже отлаживается.

Инструменты и их описания

Агенту дали четыре инструмента:

• Найти клиента по телефону, почте или имени. Только чтение.
• Посмотреть историю обращений клиента. Только чтение.
• Создать тикет с обязательными полями. Единственный инструмент с внешним эффектом.
• Передать человеку с указанием причины. Тоже завершает работу.

Что выяснилось на описаниях. Первая версия описания поиска клиента звучала как «ищет клиента в базе». Агент вызывал его постоянно, включая случаи, когда искать было нечего. Описание переписали: когда применять, когда не применять и что вернётся, если не найдено. Число лишних вызовов упало в разы.

Второй урок: инструмент передачи человеку изначально не требовал причины. Агент им пользовался как способом закончить работу, когда задача становилась сложной. Обязательное поле причины плюс проверка, что она осмысленна, вернуло его в рамки.

Первый прогон и правки

Прогнали на сотне реальных обращений. Что вылезло:

Сообщал об успехе после ошибки. Создание тикета падало на валидации, инструмент возвращал ошибку, агент писал «тикет создан». Классика. Починили не промптом, а проверкой факта: после завершения система сама убеждается, что тикет существует, и если нет - это неуспех независимо от того, что написал агент.

Путал две близкие категории. Не проблема модели: в самих определениях категорий не было границы. Границу описали явно, с примерами по обе стороны.

Слишком много шагов на простых обращениях. Агент запрашивал историю клиента там, где хватало текста обращения. Помог явный порядок: сначала попытаться решить по тексту, обращаться к базе только при недостатке данных.

Терял часть многотемного обращения. Сообщение с тремя вопросами превращалось в один тикет. Добавили явную проверку на несколько тем и разделение до основного цикла.

Что получилось

Система, где модель отвечает за разбор и за решение в неоднозначных случаях, а всё остальное - детерминированный код. Практические итоги:

• Доля обращений, уходящих человеку, - осознанная настройка, а не побочный эффект. Порог уверенности крутится в одном месте.
• Стоимость шага предсказуема, потому что большая часть работы не проходит через модель.
• Отладка возможна. По логам видно, какой инструмент вызван и что вернул, а не только итоговый текст.

Главный вывод, который переносится на другие задачи: сначала выясните, какая часть задачи действительно требует решений, и только её отдайте агенту. Остальное дешевле написать.

Как это выглядит на боевых проектах - в портфолио. Общая схема работы - в статье создание агента, а что проверить перед запуском - во внедрении. Обзор - гид по ИИ-агентам.