Статья
19 нояб. 2026 г.
чтение
Инструменты, которые вызывает ИИ, с формулировками в коде
Адам Кейлси (Adam Kalsey)
Вице-президент по продукту
Создавайте бесплатно.
Создайте пространство и запустите свой первый сценарий вызова за считанные минуты.
Голосовой ИИ
ИИ-агенты
Руководства для разработчиков
Это третья часть серии публикаций о тыкве на Хэллоуин, которую я создал для общения с детьми, выпрашивающими сладости; начало разработки описано в части 1. Во второй части у тыквы появились личность и три режима. В этой части она получает инструменты — функции на моем сервере, которые модель вызывает во время разговора. Они предоставляют модели свежий материал для четырехсотого посетителя за ночь. Кроме того, в них хранятся формулировки, которые должны быть точными, поэтому они задаются в коде, а не являются догадками модели.
Написание инструмента
Инструмент — это метод агента, отмеченный декоратором @AgentBase.tool. Декоратор задает его имя, описание и JSON-схему для его параметров. Когда модель вызывает инструмент, SignalWire отправляет запрос на мой сервер, наш Python SDK выполняет метод, а метод возвращает FunctionResult.
Тыква вызывает consult_memory, когда кто-то спрашивает о ее прошлом:
Модель читает описание, чтобы решить, когда вызывать инструмент, что превращает описание в текст промпта. В нем простыми словами указано, когда нужно вызывать инструмент и куда отправлять ближайший неподходящий случай. Перечисление enum ограничивает круг тем теми, для которых у сервера есть материалы. Результат также является текстом промпта, поскольку он содержит фрагмент вместе с инструкциями по его использованию.
Вытягивание строк из пула без повторений
Предыстория тыквы представляет собой словарь тем, и каждая тема содержит несколько фрагментов, которые намеренно противоречат друг другу:
Если спросить о ее возрасте дважды, тыква дает два разных ответа, что соответствует характеру персонажа, но давать одной группе один и тот же ответ дважды не стоит. Поэтому функция pick_unused сохраняет в global_data список фрагментов, использованных за этот визит, и выбирает из оставшихся:
Каждый отправляемый нами запрос инструмента содержит глобальные данные вызова global_data, поэтому обработчик считывает из них состояние визита и возвращает обновление вместе с результатом. Когда прибывает следующая группа, сервер сбрасывает used_fragments, и весь пул снова становится доступным.
Рассказ историй по шагам
Тыква никогда не говорит «Я не знаю». Когда посетитель спрашивает о чем-то, на что она не может ответить, она рассказывает историю, которая начинается с вопроса и уходит в сторону. tell_a_story строит каждую историю из трех абсурдных поворотов, выбранных случайным образом:
Каждый вызов возвращает только следующий этап, а текущее положение в истории хранится в global_data.story. Посетитель, который говорит «и что потом?», получает следующий поворот сюжета, а тот, кто меняет тему, оставляет историю позади.
Когда тыква должна отправить группу дальше, инструмент отказывает, потому что история — это самый верный способ заставить их стоять на месте.
Точные формулировки для граничных случаев
Некоторые запросы требуют одинакового ответа каждый раз. Посетитель просит потрогать тыкву, хочет сфотографироваться, ругается матом, делится своим адресом или говорит «ты — искусственный интеллект». decline_to_answer принимает тип запроса и возвращает рекомендации для него из таблицы:
Модель распознает момент и выбирает категорию, а ответ хранится в коде, где я могу его проверить и протестировать.
Собственная копия инструмента для каждого режима
Некоторые инструменты требуют других формулировок в мягком режиме (gentle mode): уютную историю вместо грандиозной и мягкий отказ вместо холодного. Я регистрирую мягкую копию каждого из таких инструментов и указываю в шаге мягкого режима только эти копии.
Каждая копия повторно использует описание, параметры и настройки оригинала, а обработчик настроен на мягкие формулировки:
Шаг мягкого режима не содержит оригиналов, поэтому у модели в мягком режиме нет доступа к формулировкам основного режима.
Тестирование инструмента без вызова
swaig-test запускает инструмент так, как это сделал бы SignalWire, с переданными вами аргументами и любыми global_data, которые должен содержать запрос:
Вторая команда никогда не возвращает фрагмент о вторнике, сколько бы раз вы ее ни запускали. Команда --list-tools показывает каждый зарегистрированный инструмент, и мягкие копии присутствуют в этом списке.
Ловушки, которых следует избегать
Не заставляйте один и тот же инструмент считывать флаг режима для выбора формулировки. Флаг в global_data может рассинхронизироваться с реальным режимом агента, а запрос инструмента не содержит информации о том, из какого контекста он поступил. Зарегистрируйте отдельную копию для каждого режима и указывайте ее только в шагах этого режима, чтобы контекст определялся автоматически.
Не давайте модели многошаговый план для самостоятельного прохождения. Получив все три поворота истории одновременно, модель склонна выдать их на одном дыхании или потерять нить повествования. Возвращайте по одному шагу за вызов и отслеживайте состояние на сервере.
Далее
Тыква умеет разговаривать и ей есть что сказать, но она не видит, с кем общается. В части 4 у нее появятся глаза, и она будет проверять камеру перед принятием любого важного решения.
Серия статей
- Система и вызов.
Система и вызов.
- Агент: личность и три режима в качестве контекстов и шагов.
Агент: личность и три режима в качестве контекстов и шагов.
- Инструменты: то, что ИИ вызывает на моем сервере, и почему его материал хранится в коде (эта публикация).
Инструменты: то, что ИИ вызывает на моем сервере, и почему его материал хранится в коде (эта публикация).
- Зрение: как дать агенту возможность видеть и проверять камеру перед принятием любых важных решений.
Зрение: как дать агенту возможность видеть и проверять камеру перед принятием любых важных решений.
- Сцена: определение того, кто стоит перед тыквой, в браузере.
Сцена: определение того, кто стоит перед тыквой, в браузере.
- Голос: аудиоэффекты в браузере.
Голос: аудиоэффекты в браузере.
- Темп и состояние: сервер ведет счет.
Темп и состояние: сервер ведет счет.
- Оператор: человек с телефоном, который может отменить действия агента.
Оператор: человек с телефоном, который может отменить действия агента.
- Тестирование и работа в течение всей ночи.
Тестирование и работа в течение всей ночи.












