Шаг 4 из 5

Инструменты агента

Единый реестр инструментов — справочник «Инструменты агента» (СИ_ИнструментыАгента). В нём живут инструменты двух типов: инструменты 1С (обработчик в общем модуле) и MCP-инструменты (из подключённых серверов). Для модели оба типа выглядят одинаково.

Регистрация базовых инструментов

Встроенные инструменты регистрируются кнопкой «по умолчанию» в форме списка справочника. Регистрация идемпотентна — повторный запуск обновляет описания и схемы уже существующих инструментов, поэтому её безопасно выполнять после каждого обновления расширения. Требуется роль СИ_АдминистрированиеЧатАгента.

Базовый набор

Инструмент	Группа	Что делает
`ExecuteDBQuery`	Основные	запрос к БД на чтение (директивы РАЗРЕШЕННЫЕ и ПЕРВЫЕ добавляются автоматически)
`GetMetadataSchema`	Основные	схема метаданных конфигурации
`GetCurrentDateTime`	Основные	текущие дата и время базы
`ParsePeriod`	Основные	разбор словесного периода («прошлый месяц») в даты
`Calculate`	Основные	точный расчёт арифметического выражения
`DrawMermaid`	Основные	Mermaid-диаграмма в файл диалога (через MCP `render_mermaid`)
`RecognizeImage`	Основные	распознавание изображений и PDF (vision-модель)
`CreateDialogFile` и др.	Основные	файлы диалога: создание, изменение, чтение, список
`GetRecentErrors`	Диагностика	свежие ошибки пользователя из журнала регистрации
`ExportTable`	Выгрузки и диаграммы	выгрузка данных в Excel
`DrawChart`	Выгрузки и диаграммы	диаграмма-карточка прямо в чате

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

Интерфейс чата AI-агента в 1С: список диалогов, инструменты по группам, ответы с таблицами — Реестр инструментов в чате: инструменты по группам, с признаками и датами регистрации

Свой инструмент: порядок создания

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

Ключевые поля элемента реестра

Поле	Как заполнить
Имя функции	уникальное имя для модели — латиница, camelCase (например, `Calculate`); по нему модель вызывает инструмент
Описание	семантика инструмента для модели — именно она определяет, когда модель будет его вызывать
Параметры Schema	JSON Schema параметров: `type: object` + `properties` + `required`; форма подставляет заготовку
Имя функции обработчика	`ИмяМодуля.ИмяФункции` — экспортная функция серверного общего модуля
Запрашивать разрешение	подтверждение пользователя перед исполнением — ставьте для пишущих инструментов
Группа (родитель)	папка реестра; «Основные» — всегда в промпте
Ключевые слова	слова вопроса, по которым группа поднимается в промпт
Разрешённые режимы (ТЧ)	список режимов; пусто — доступен во всех режимах

Контракт обработчика

// Параметры:
//  Аргументы - Структура - параметры, которые передала модель.
//
// Возвращаемое значение - Структура:
//  * Успех    - Булево.
//  * Значение - Произвольный - результат; сериализуется в JSON и уходит модели.
//  * Ошибка   - Строка, Неопределено - текст ошибки при Успех = Ложь.
Функция Калькулятор(Аргументы) Экспорт
	Результат = Новый Структура("Успех, Значение, Ошибка", Ложь, Неопределено, Неопределено);
	// ...
	Возврат Результат;
КонецФункции

Для пишущих инструментов (создание документов, файлов, внешние запросы) всегда включайте «Запрашивать разрешение» — перед исполнением появится подтверждение в чате.

Обработчики недоверенных модулей исполняются под безопасным режимом платформы: привилегированные возможности в них недоступны. Доверенные модули (СИ_Инструменты1С, СИ_ФайлыДиалога, СИ_РаспознованиеИзображений) вызываются без безопасного режима через статическую диспетчеризацию — список методов там ведётся вручную.