DF-ИИ-042 · ИИ в работе команды
Свой ИИ-агент с нуля: проверки до первого действия
- Из чего состоит первый агент: модель, инструменты, память и цикл
- Как описать инструменты, чтобы модель вызывала их предсказуемо
- Где поставить проверки до первого действия агента
- Чек-лист решений и точки остановки перед запуском
Вы просите агента «разобраться с заявкой», а он уверенно отвечает, что всё сделано, — хотя ничего не произошло. Или наоборот: без спроса отправляет письмо клиенту, потому что так показалось логичнее. Оба случая — не про «плохую модель», а про обвязку вокруг неё: описание инструментов, обработку вызовов и точки остановки.
Первый агент почти никогда не ломается на генерации текста. Он ломается на стыке: модель решила вызвать инструмент, а код не был готов к такому ответу; не хватило параметра, и модель его придумала; необратимое действие прошло без подтверждения. Ниже — как разложить агента на шаги и какие проверки добавить до того, как он начнёт действовать.
Это редакционный чек-лист Deskforge, а не отчёт об испытании продукта и не клиентский кейс: шаги нужно адаптировать к вашему стеку и вашим правилам. Смежная тема — из чего состоит ИИ-агент, а варианты работ с ИИ собраны на странице автоматизации процессов.
Из чего состоит первый агент: модель, инструменты, память и цикл
Полезно сразу отделить модель от всего остального. В документации LangChain агент описан коротко: модель плюс обвязка — промпт, инструменты и middleware, которые задают поведение. Модель — это генератор решений; обвязка — то, что вы контролируете и проверяете.
Вторая часть — цикл. Модель не выполняет действие сама: она решает, что действие нужно, а выполняет его ваш код. В tool use у Claude модель определяет, когда вызвать инструмент, опираясь на запрос пользователя и описание инструмента. То есть предсказуемость вызова зависит не только от модели, но и от того, насколько ясно вы описали инструмент.
Память и состояние — третий элемент. Для первого агента достаточно, чтобы в цикле было понятно, что уже сделано и с каким результатом: без этого агент повторяет шаги или теряет контекст между вызовами. Держите это в явном виде, а не «в голове» модели.
Как описать инструменты, чтобы модель вызывала их предсказуемо
Начните с механики вызова. При клиентском инструменте модель возвращает блок tool_use, ваше приложение выполняет операцию и отправляет обратно tool_result. Значит, обработчик должен быть готов и к вызову, и к результату — это два разных шага, и оба нужно проверить.
Второе — строгая схема. В OpenAI API strict-режим требует additionalProperties: false и пометки всех полей как required; при несоответствии схемы запрос отклоняется. У Claude флаг strict: true в определении инструмента обеспечивает точное соответствие вызова схеме. Это не украшение: строгая схема отсекает часть вызовов, которые иначе пришлось бы ловить в коде.
Третье — само описание. Если в описании инструмента не сказано, какие параметры обязательны и что делать при их отсутствии, модель заполнит пробел по-своему. Проверьте описание так, как его увидит модель: коротко, однозначно, с примерами допустимых значений.
Где поставить проверки до первого действия агента
Проверки ставятся не после запуска, а до него — на синтетических запросах. Возьмите несколько типовых сценариев и прогоните их вручную, глядя на ответ модели, а не только на финальный текст.
Первый сценарий — неполный запрос. В документации Claude приведён пример: если спросить про погоду, не указав город, модель может подставить значение, которого пользователь не называл. Проверьте, что делает ваш агент: спрашивает или молча угадывает. Для необратимых действий второе недопустимо.
Второй сценарий — несколько вызовов в одном ответе. В OpenAI API вызов инструмента — это многошаговый обмен: запрос с инструментами, вызов от модели, выполнение кода, повторный запрос с результатом и финальный ответ. Ответ может содержать ноль, один или несколько вызовов, поэтому обработку стоит писать с расчётом на массив. Проверьте обработчик на ответе с массивом вызовов, а не только на одиночном.
Третий сценарий — ограничение набора инструментов. Параметр tool_choice позволяет ограничить или зафиксировать инструменты, которые модель может вызвать. Задайте его и убедитесь, что на шаге доступны только нужные инструменты, а лишние не проходят.
Точки остановки и участие человека в цикле
Самая дорогая ошибка первого агента — необратимое действие без подтверждения: отправленное письмо, изменённая запись, списанные деньги. Такие действия должны упираться в точку остановки, где решение принимает человек.
Технически это проще, чем кажется. Агенты LangChain построены на LangGraph, что даёт устойчивое выполнение и поддержку участия человека в цикле. То есть пауза перед действием — штатная часть цикла, а не костыль поверх него.
Практическое правило: разделите действия на обратимые и необратимые. Обратимые агент выполняет сам, необратимые — только после подтверждения. Это дешевле, чем разбирать последствия.
Чек-лист решений перед запуском агента
Соберите проверки в один список и пройдите его до первого реального запроса. Ниже — минимальный набор, который закрывает самые частые сбои.
- Описано ли, когда агент вызывает инструмент, а когда отвечает сам? Сверьте описание инструмента и системный промпт с ожидаемым поведением.
- Что произойдёт, если обязательный параметр не указан? Прогоните запрос без параметра и посмотрите, спросит агент или подставит значение.
- Обрабатывает ли код несколько вызовов в одном ответе? Проверьте обработчик на ответе с массивом вызовов.
- Соответствует ли схема инструмента строгому режиму? Проверьте additionalProperties и список required в схеме.
- Ограничен ли набор инструментов на один шаг? Задайте tool_choice и убедитесь, что доступны только нужные инструменты.
- Есть ли точка остановки перед необратимым действием? Включите подтверждение человека перед выполнением действия.
Если хотя бы один пункт не проходит, агент ещё не готов действовать. Это нормальный результат проверки, а не повод запускать «как есть» и смотреть, что выйдет.