Создание ИИ-агента: с чего начать и где всё обычно ломается

Агент и чат-бот: разница в одном

Чат-бот выдаёт текст. Агент выдаёт результат действия: читает документ, дёргает API, обновляет строку в таблице, запускает скрипт. Право на действие и есть граница между ними.

Внутри любой агент собран из четырёх деталей:

• Модель — принимает решения на каждом шаге.
• Инструменты — функции, которые модель вызывает: поиск, запрос к базе, отправка письма.
• Контекст — системная инструкция, данные задачи, история шагов.
• Цикл — модель выбирает инструмент, получает результат, решает следующий шаг, и так до остановки.

Остальное — обвязка вокруг этих четырёх деталей.

Шаг 1. Опишите задачу до уровня операции

Формулировка «агент для работы с клиентами» нерабочая. Рабочая звучит так: «читает входящее письмо, находит клиента в CRM, составляет черновик ответа и кладёт его в задачу менеджеру».

Проверьте свою формулировку тремя вопросами:

• Что на входе и в каком виде?
• Какие ровно действия допустимы?
• Как выглядит успешный результат, который можно посмотреть глазами?

Если на третий вопрос ответа нет, собирать агента рано.

Шаг 2. Соберите список инструментов

Инструмент — обычная функция с понятным именем и описанием. Модель читает описание и решает, вызывать её или нет.

Практика, которая экономит часы отладки:

• Одна функция — одно действие. «Универсальный» инструмент с десятью режимами модель путает.
• Описание пишите для человека, который видит систему впервые. Модель читает его так же.
• Возвращайте текст, пригодный для чтения. Сырой JSON на двести строк засоряет контекст.
• Опасные операции — удаление, оплату, отправку наружу — выносите за подтверждение человека.

Шаг 3. Запустите цикл

Цикл выглядит буквально так: отправили запрос модели → получили вызов инструмента → выполнили → вернули результат → повторили. Останов по условию: задача решена, лимит шагов исчерпан, инструмент вернул ошибку.

Собрать его можно тремя путями:

• Руками через API. Полный контроль, кода немного, всё прозрачно. Годится для первой версии.
• Готовый SDK — например, Claude Agent SDK. Цикл, вызов инструментов и работа с файлами уже внутри.
• Визуальные платформы вроде n8n. Быстрый старт без кода, потолок наступает на нестандартной логике.

Для первого агента берите API напрямую. Так вы своими глазами увидите, где именно модель ошибается.

Шаг 4. Проверьте на настоящих данных

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

Смотрите на три вещи: правильно ли выбран инструмент, корректны ли аргументы, разумно ли агент вышел из ошибки.

Где всё обычно ломается

Слишком широкая задача. Агент «на всё» работает хуже трёх узких.

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

Бесконечный цикл. Жёсткий лимит шагов ставьте с первой строки кода.

Отсутствие логов. Без записи каждого вызова разбор ошибки превращается в гадание. Логируйте запрос, вызов инструмента, результат.

Полное доверие с первого дня. Первые недели держите человека на выходе. Автономию отдавайте кусками, по мере того как накапливается статистика.

Когда агент избыточен

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

С чего начать на этой неделе

Возьмите рутину, которая съедает у вас полчаса в день. Опишите её так, как в шаге 1. Соберите два инструмента. Прогоните два десятка реальных случаев и посмотрите на логи.

Первая версия помещается в один файл. Этого хватает, чтобы понять, стоит ли развивать дальше.