# Создание инструментов

Руководство по разработке инструментов для агентов.

## Типы инструментов

| Тип           | Описание           | Когда использовать  |
| ------------- | ------------------ | ------------------- |
| HTTP (код 1С) | Выполняет код в 1С | Работа с данными 1С |
| MCP           | Внешний MCP сервер | Внешние системы     |
| OneRPA        | Робот OneRPA       | UI автоматизация    |

## Создание HTTP инструмента

### Шаг 1: Планирование

```
Инструмент: Получить остаток товара
Назначение: Возвращает остаток товара на складе
Вход: Наименование товара
Выход: Количество, единица измерения
```

### Шаг 2: Создание

1. Справочник "Инструменты" → Создать
2. Наименование: `Получить остаток товара`
3. Описание:

```
Возвращает текущий остаток товара на складе.
Используй, когда пользователь спрашивает:
- Сколько товара на складе
- Есть ли товар в наличии
- Какой остаток по товару
```

### Шаг 3: Код

```bsl
// Получение параметра
НаименованиеТовара = Параметры.Товар;

// Поиск товара
Запрос = Новый Запрос;
Запрос.Текст = 
"ВЫБРАТЬ
|    Остатки.Номенклатура.Наименование КАК Товар,
|    Остатки.КоличествоОстаток КАК Количество,
|    Остатки.Номенклатура.ЕдиницаИзмерения.Наименование КАК Единица
|ИЗ
|    РегистрНакопления.ТоварыНаСкладах.Остатки КАК Остатки
|ГДЕ
|    Остатки.Номенклатура.Наименование ПОДОБНО &Наименование";

Запрос.УстановитьПараметр("Наименование", "%" + НаименованиеТовара + "%");
Выборка = Запрос.Выполнить().Выбрать();

// Формирование результата
Результаты = Новый Массив;
Пока Выборка.Следующий() Цикл
    Результаты.Добавить(Новый Структура(
        "Товар, Количество, Единица",
        Выборка.Товар,
        Выборка.Количество,
        Выборка.Единица
    ));
КонецЦикла;

Результат = Новый Структура("Товары", Результаты);
```

### Шаг 4: Параметры

| Имя   | ИмяEn   | Тип    | Описание                       |
| ----- | ------- | ------ | ------------------------------ |
| Товар | product | string | Наименование товара для поиска |

## Описание инструмента

### Важность описания

LLM использует описание чтобы понять:

* Что делает инструмент
* Когда его вызывать
* Какие параметры передать

### Структура описания

```
1. Что делает инструмент (одно предложение)
2. Когда использовать (примеры запросов)
3. Важные ограничения (если есть)
```

### Хороший пример

```
Возвращает текущий остаток товара на складе по наименованию.

Используй этот инструмент, когда пользователь:
- Спрашивает о наличии товара
- Хочет узнать количество на складе
- Интересуется запасами

Ограничение: поиск по частичному совпадению названия,
может вернуть несколько товаров.
```

### Плохой пример

```
Остатки товаров
```

## Параметры инструмента

### Типы

| Тип        | JSON    | Пример    |
| ---------- | ------- | --------- |
| Строка     | string  | "Товар А" |
| Число      | number  | 123.45    |
| Целое      | integer | 42        |
| Логическое | boolean | true      |

### Описание параметров

Описание помогает LLM понять, что передавать:

```
Параметр: period
Описание: Период отчёта в формате YYYY-MM (например, 2026-01)
```

## Формат ответа

### Простой результат

```bsl
Результат = Новый Структура("Остаток", 150);
```

### Структурированный результат

```bsl
Результат = Новый Структура;
Результат.Вставить("Товар", "Товар А");
Результат.Вставить("Остаток", 150);
Результат.Вставить("Единица", "шт");
Результат.Вставить("Склад", "Основной");
```

### Список результатов

```bsl
Результаты = Новый Массив;
Для Каждого Строка Из Таблица Цикл
    Результаты.Добавить(Новый Структура(
        "Поле1, Поле2",
        Строка.Поле1,
        Строка.Поле2
    ));
КонецЦикла;
Результат = Новый Структура("Данные", Результаты);
```

## Обработка ошибок

```bsl
Попытка
    // Основной код
    ...
    Результат = Новый Структура("Успех, Данные", Истина, Данные);
Исключение
    Результат = Новый Структура(
        "Успех, Ошибка",
        Ложь,
        ОписаниеОшибки()
    );
КонецПопытки;
```

## Тестирование инструмента

1. Создайте тестового агента только с этим инструментом
2. Синхронизируйте с Proxy
3. В чате попросите использовать инструмент:

   ```
   Используй инструмент "Получить остаток товара" 
   для товара "Ноутбук"
   ```
4. Проверьте результат

## Далее

{% content-ref url="/pages/2eJAsRmkyJBpg56rIHoY" %}
[Работа с промптами](/ai-platforma-oneapa/razrabotka-agentov/rabota-s-promptami.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/razrabotka-agentov/sozdanie-instrumentov.md?ask=<question>
```

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.