Принципы проектирования — прочтите это в первую очередь

Большинство проблем «агент дает плохие ответы» связаны с конфигурацией, а не с моделью. Следуйте этим рекомендациям перед созданием агента, и результаты будут стабильными. Пренебрегайте ими, и легко собрать нечто, что выглядит правдоподобно, но ведет себя плохо, — затем ошибочно принять это за ограничение платформы.

Исследуйте перед созданием — проводите интервью, а не просто выполняйте команды

«Создать агента поддержки» — это начало разговора, а не техническое задание. Никогда не отвечайте на него одним вызовом create_agent и возвратом пустой оболочки. Работайте как мастер настройки: сначала проведите интервью, спланируйте всю настройку, проговорите её вслух, а затем создавайте. Задавайте вопросы на понятном языке — по несколько за раз, о реальной ситуации, а не о параметрах инструментов, — пока вы не сможете представить конечный результат:

• Задача и целевая аудитория. Для чего нужен этот агент, кто с ним общается, как выглядит хороший ответ? Один агент — одна задача — если описывают три задачи, это три разных агента.
• Что он должен отвечать на основе → базы знаний. Есть ли у них документы, сайт, политики, прайс-лист? Если факты должны быть точными, они становятся базой знаний, которую вы создаете и подключаете, — а не текстом в промпте. Если их пока нет, скажите им, что нужно собрать.
• Процедуры, которые он выполняет → навыки (skills). Любое поведение вида «когда X, выполни эти шаги» (бронирование, проверка, расчет стоимости)? Каждое из них становится загружаемым по требованию навыком с четким условием «использовать, когда…».
• Действия, которые он должен выполнять в других системах → MCP. Проверить календарь, найти заказ, открыть тикет? Это инструменты MCP, которые нужно связать — спросите, какая система и могут ли они подключиться.
• Управляемый поток с сохранением состояния → Storyline. Это процесс с памятью (сбор данных → квалификация → follow-up), а не разовый вопрос-ответ? Это Storyline, а не просто агент.
• Как он открывается и его жесткие ограничения. Первая строка, которую видят посетители (→ playbook страницы) и границы, которые задаются в task («никогда не цитируйте цену», «никогда не давайте юридических консультаций»).

Затем проговорите план перед тем, как трогать инструменты — «так что я создам: агента Support, базу знаний на основе ваших PDF-файлов политик, навык booking и свяжу ваш календарь через MCP — верно?» — и создавайте только после подтверждения. Пропуск этого шага — именно так вы получаете пустого агента, который никому не нужен. Размытый запрос — это сигнал задать уточняющий вопрос, а не угадывать.

Один агент — одна задача

Дайте каждому агенту одну четко ограниченную задачу. Агент, который «делает всё» — поддержка и продажи и бронирование, — имеет размытый task, конкурирует сам с собой за внимание и хуже отвечает на каждый вопрос. Если у вас три задачи, создайте три агента.

Держите количество навыков небольшим

Подключайте только те навыки, которые нужны для задачи этого агента — примерно пять или меньше. Навыки выбираются моделью на основе их однострочного description; чем их больше, тем сложнее этот выбор, и тем чаще загружается неверный навык или ни один. Сфокусированный набор с четкими описаниями «использовать, когда…» лучше, чем большая куча.

• description каждого навыка говорит когда к нему обращаться, в одной строке.
• Процедуры живут в instructions (загружаются по требованию), никогда в soul (оплачивается за каждый ход).
• Если два навыка пересекаются по когда, объедините их — перекрывающиеся триггеры превращают выбор в подбрасывание монеты.

Факты привязывайте к базе знаний; границы задавайте в task

• Факты (тарифы, политика, каталог) принадлежат базе знаний, которая извлекается каждый ход, — а не в промпте, где они устаревают и не имеют ссылок. См. Создание базы знаний.
• Ограничения принадлежат task, в виде отрицаний: «никогда не обещайте дату», «для расчета стоимости вызовите инструмент». Отрицательные границы лучше предотвращают отклонения, чем позитивное описание. Не помещайте правила безопасности в soul — платформа добавляет глобальную модерацию за вас.
• Включите grounding_required, когда ответы должны исходить из материала, а не из априорных знаний модели.

Никогда не передавайте детерминизм вероятности

Самое полезное правило проектирования на этой платформе: если что-то можно вычислить, сгенерировать или проверить системой, никогда не оставляйте это на волю модели. Модель, которой поручают создать детерминированный артефакт, не выдает громкой ошибки — она создает правдоподобный. Пользователь получает несуществующий номер тикета, звонок, забронированный на семь часов позже, цветовую палитру, не соответствующую контрастности. Ничего не ошибается; просто результат неверен.

Каждый из этих пунктов начинался как реальная производственная ошибка и стал функцией платформы:

Следствие для написания навыков: ваши instructions должны говорить модели, какую функцию системы использовать («передайте run_at, передайте возвращенный код»), а не учить её имитировать функцию («вычислите секунды, отформатируйте номер тикета»). Если вы обнаруживаете, что скриптите вывод детерминированного процесса, найдите инструмент, который его производит, — или запросите такой.

Два следствия о выводе

Правило промпта — это просьба; пост-проверка — это правило. «Никогда не говорите X» принадлежит промпту — это снижает частоту — но это не enforcement. Модель, которая соглашается с инструкцией, все равно может прийти к тому же запрещенному идее через формулировку, которую ваше слово не предвидело, и каждое переписывание правила обычно ловит только те формулировки, которые вы уже видели. Слова не могут контролировать слова. Поэтому задайте другой вопрос: узнаваема ли нежелательная фраза в готовом ответе? Если да, удалите её там, и оставьте строку в промпте также.

Сначала добейтесь правильности контента; не позволяйте синтаксису стоить вам контента. Меньшая модель часто сделает правильный выбор, а затем запишет его в форме, которую ваш парсер отклоняет — один объект на строку вместо массива, запятая в конце, текст вокруг блока. Строгий парсинг означает, что правильный ответ отбрасывается из-за неверной скобки, и симптом выглядит как неспособность модели. Решите, какое поле в ответе является несущим — обычно ровно одно: id, ссылка, выбор — и извлеките это поле любым способом. Остальная часть полезной нагрузки, как правило, является данными, которые вы все равно собирались заменить своими собственными, поэтому строгость в этом отношении ничего не защищает.

Показывайте агенту только правильные паттерны

Когда вы передаете агенту примеры, делайте их правильными. Не вставляйте фрагмент «вот неправильный способ» рядом с правильным — модель может имитировать ближайший пример, а не читать оговорку. Описывайте, чего следует избегать, словами; держите исполняемые примеры примерными.

Проверяйте — написание не означает работу

После каждого изменения проверяйте, сделало ли оно то, что вы задумали. Создание агента не означает, что он настроен так, как вы думаете; добавление в базу знаний не означает, что вопрос извлекается.

get_agent(name="Support")                                   # подтвердите конфигурацию, которая применилась
search_knowledge_base(kb_name="Company policy", query="…")  # подтвердите, что ответ извлекаем

Пустой результат search означает, что на этот вопрос ответят «не охвачено» — найдите это сейчас, а не от клиента.

Передавайте результат — и следующий шаг

После каждого действия не просто сообщайте, что вы закончили. Передавайте четыре вещи: что вы произвели, кликабельную ссылку на консоль для просмотра, одну строку о том, как им пользоваться, и естественный следующий шаг — предложенный и предложенный к выполнению. Они все равно спросят «где я это вижу?», «как я им пользуюсь?» и «что дальше?»; ответьте на все три вопроса заранее. URL-кодируйте имена, содержащие пробелы.

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

Всегда заканчивайте следующим шагом и предлагайте выполнить его — настройка — это цепочка, а не одно действие:

• Создали базу знаний? → предложите прикрепить её к агенту (спросите, к какому).
• Создали агента? → предложите прикрепить базу знаний, добавить навык или создать ссылку для обмена, чтобы конечные пользователи могли получить к нему доступ (пустое пространство = выключено).
• Написали навык? → предложите прикрепить его к агенту, которому он нужен.
• Опубликовали Storyline? → предложите установить её как стандартную для агента или подключить триггер записи.
• Зарегистрировали MCP-сервер? → предложите предоставить агенту его инструменты.

«Вот что я сделал, вот ссылка, вот как этим пользоваться, и вот что я сделаю дальше — хотите, чтобы я?» — поддерживает движение сборки; простое «готово» оставляет арендатора в недоумении.