# Инструменты
Справочник `APA_Инструменты` определяет функции, которые агенты могут вызывать для получения данных или выполнения действий.
## Назначение
Инструмент — это функция, которую агент может вызвать:
* Запрос данных из 1С
* Вызов внешнего API
* Запуск робота OneRPA
* Взаимодействие через MCP
## Характеристики справочника
| Параметр | Значение |
| ------------- | ---------------- |
| Имя | APA\_Инструменты |
| Иерархический | Да |
| Владельцы | Нет |
## Реквизиты
### Основные реквизиты
| Реквизит | Тип | Описание |
| -------------------- | -------------------------- | -------------------- |
| **Код** | Строка(9) | Уникальный код |
| **Наименование** | Строка(150) | Название инструмента |
| **Описание** | Строка(0) | Описание для LLM |
| **ЗапросКод** | Строка(0) | Код на языке 1С |
| **MCP** | Булево | Инструмент через MCP |
| **OneRPA** | Булево | Инструмент OneRPA |
| **Формат** | Справочник.APA\_Форматы | Формат ответа |
| **ВариантОтчета** | Справочник.ВариантыОтчетов | Вариант отчёта |
| **КодЗаданияOneRPA** | Строка | Код задания OneRPA |
### Табличные части
#### Параметры
| Колонка | Тип | Описание |
| -------- | ------ | ------------------------------------- |
| Имя | Строка | Имя параметра (на русском) |
| ИмяEn | Строка | Имя параметра (на английском) |
| Описание | Строка | Описание параметра для LLM |
| Тип | Строка | Тип: string, number, integer, boolean |
#### Доступность
| Колонка | Тип | Описание |
| ------------ | ---------------------------- | ---------------------- |
| Пользователь | Справочник.APA\_Пользователи | Кто может использовать |
## Типы инструментов
### HTTP инструмент (код 1С)
Выполняет код на языке 1С и возвращает результат.
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Инструмент: Получить остаток отпуска │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ☐ MCP ☐ OneRPA │
│ │
│ Описание: │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Возвращает количество оставшихся дней отпуска для сотрудника. │ │
│ │ Используй этот инструмент, когда пользователь спрашивает │ │
│ │ об остатке отпуска. │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Код: │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Сотрудник = Параметры.Сотрудник; │ │
│ │ │ │
│ │ Запрос = Новый Запрос; │ │
│ │ Запрос.Текст = "ВЫБРАТЬ ОстатокДней ИЗ ..."; │ │
│ │ Запрос.УстановитьПараметр("Сотрудник", Сотрудник); │ │
│ │ Результат = Запрос.Выполнить().Выгрузить(); │ │
│ │ │ │
│ │ Возврат = Новый Структура("Дней", Результат[0].ОстатокДней); │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Параметры: │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Сотрудник | employee | string | ФИО или табельный номер сотрудника│ │
│ └────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
### MCP инструмент
Вызывает внешний MCP сервер.
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Инструмент: Поиск в файлах │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ☑ MCP ☐ OneRPA │
│ │
│ Описание: │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Ищет текст в файлах на сервере. Используй для поиска │ │
│ │ информации в документах. │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Параметры: │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ query | query | string | Поисковый запрос │ │
│ │ path | path | string | Путь для поиска │ │
│ └────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
### OneRPA инструмент
Запускает робота OneRPA.
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Инструмент: Выгрузка отчёта в Excel │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ☐ MCP ☑ OneRPA │
│ │
│ Код задания OneRPA: [EXPORT_EXCEL_001 ] │
│ │
│ Описание: │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Выгружает указанный отчёт в Excel файл. Используй, когда │ │
│ │ пользователь просит сформировать отчёт в Excel. │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Параметры: │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ report_name | report_name | string | Название отчёта │ │
│ │ period_from | period_from | string | Дата начала периода │ │
│ │ period_to | period_to | string | Дата конца периода │ │
│ └────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
## Создание инструмента
### Шаг 1: Базовые настройки
1. Откройте справочник "Инструменты"
2. Нажмите "Создать"
3. Введите **Наименование**
4. Выберите тип (обычный/MCP/OneRPA)
### Шаг 2: Описание
Напишите понятное **Описание** для LLM:
**Хорошее описание:**
```
Возвращает текущий остаток денежных средств на расчётном счёте компании.
Используй этот инструмент, когда пользователь спрашивает о балансе,
остатке на счёте или доступных средствах.
```
**Плохое описание:**
```
Остаток на счёте
```
### Шаг 3: Параметры
Добавьте параметры на вкладке "Параметры":
| Имя | ИмяEn | Тип | Описание |
| ---- | ------- | ------ | -------------------------- |
| Счёт | account | string | Номер расчётного счёта |
| Дата | date | string | Дата для получения остатка |
### Шаг 4: Код (для HTTP инструментов)
Напишите код на языке 1С:
```bsl
// Получение параметров
НомерСчёта = Параметры.Счёт;
Дата = Параметры.Дата;
// Выполнение запроса
Запрос = Новый Запрос;
Запрос.Текст =
"ВЫБРАТЬ
| Остатки.СуммаОстаток КАК Остаток
|ИЗ
| РегистрНакопления.ДенежныеСредства.Остатки(&Дата) КАК Остатки
|ГДЕ
| Остатки.Счёт.Номер = &НомерСчёта";
Запрос.УстановитьПараметр("Дата", Дата);
Запрос.УстановитьПараметр("НомерСчёта", НомерСчёта);
Выборка = Запрос.Выполнить().Выбрать();
Если Выборка.Следующий() Тогда
Результат = Новый Структура("Остаток", Выборка.Остаток);
Иначе
Результат = Новый Структура("Остаток", 0);
КонецЕсли;
```
### Шаг 5: Сохранение
1. Нажмите "Записать"
2. Добавьте инструмент к агенту
3. Выполните синхронизацию с Proxy
## Типы параметров
| Тип | Описание | Пример значения |
| --------- | --------------- | --------------- |
| `string` | Строка | "Иванов И.И." |
| `number` | Число (дробное) | 123.45 |
| `integer` | Целое число | 42 |
| `boolean` | Логическое | true/false |
## Формат ответа
Для структурированного ответа используйте справочник "Форматы":
```json
{
"остаток": 1500000.50,
"валюта": "RUB",
"дата": "2026-01-23"
}
```
## Примеры инструментов
### Получение данных
```bsl
// Инструмент: Список неоплаченных счетов
// Параметры: Контрагент (string)
Контрагент = Параметры.Контрагент;
Запрос = Новый Запрос;
Запрос.Текст =
"ВЫБРАТЬ
| Счета.Номер,
| Счета.Сумма,
| Счета.ДатаОплаты
|ИЗ
| Документ.СчётНаОплату КАК Счета
|ГДЕ
| Счета.Контрагент.Наименование ПОДОБНО &Контрагент
| И НЕ Счета.Оплачен";
Запрос.УстановитьПараметр("Контрагент", "%" + Контрагент + "%");
Таблица = Запрос.Выполнить().Выгрузить();
Результат = Новый Массив;
Для Каждого Строка Из Таблица Цикл
Результат.Добавить(Новый Структура(
"Номер, Сумма, ДатаОплаты",
Строка.Номер, Строка.Сумма, Строка.ДатаОплаты
));
КонецЦикла;
```
### Создание документа
```bsl
// Инструмент: Создать заявку на отпуск
// Параметры: Сотрудник (string), ДатаС (string), ДатаПо (string)
Сотрудник = Параметры.Сотрудник;
ДатаС = Дата(Параметры.ДатаС);
ДатаПо = Дата(Параметры.ДатаПо);
Заявка = Документы.ЗаявкаНаОтпуск.СоздатьДокумент();
Заявка.Дата = ТекущаяДата();
Заявка.Сотрудник = НайтиСотрудника(Сотрудник);
Заявка.ДатаНачала = ДатаС;
Заявка.ДатаОкончания = ДатаПо;
Заявка.Записать();
Результат = Новый Структура(
"Успех, НомерЗаявки",
Истина, Заявка.Номер
);
```
## Доступность инструментов
### Ограничение по пользователям
На вкладке "Доступность" укажите, кто может использовать инструмент:
* Если список пуст — доступен всем
* Если есть пользователи — только им
### Контекстная доступность
Агент видит только те инструменты, которые:
1. Добавлены в агента
2. Доступны текущему пользователю
## Устранение проблем
### Инструмент не вызывается
1. Проверьте, добавлен ли инструмент в агента
2. Проверьте описание — LLM должен понимать, когда использовать
3. Укажите в промпте агента про инструмент
### Ошибка выполнения кода
1. Проверьте синтаксис кода 1С
2. Проверьте наличие объектов в базе
3. Смотрите регистр APA\_ЛогИнструментов
### Неверные параметры
1. Проверьте имена параметров (ИмяEn)
2. Проверьте типы параметров
3. Проверьте описания параметров
## Далее
{% content-ref url="/pages/Ow1QsUULaU4zVYdanIpA" %}
[Модели](/ai-platforma-oneapa/spravochniki/modeli.md)
{% endcontent-ref %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.onerpa.ru/ai-platforma-oneapa/spravochniki/instrumenty.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.