> For the complete documentation index, see [llms.txt](https://docs.onerpa.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onerpa.ru/ai-platforma-oneapa/spravochniki/formaty.md).

# Форматы

Справочник `APA_Форматы` определяет форматы выходных данных для инструментов.

## Назначение

Форматы используются для:

* Структурирования ответов инструментов
* Указания LLM ожидаемого формата данных
* Валидации результатов

## Характеристики справочника

| Параметр      | Значение     |
| ------------- | ------------ |
| Имя           | APA\_Форматы |
| Иерархический | Нет          |
| Владельцы     | Нет          |

## Реквизиты

| Реквизит         | Тип         | Обязательный | Описание           |
| ---------------- | ----------- | ------------ | ------------------ |
| **Код**          | Строка(9)   | Да           | Уникальный код     |
| **Наименование** | Строка(150) | Да           | Название формата   |
| **ТекстJSON**    | Строка(0)   | Да           | JSON схема формата |

## Форма элемента

```
┌─────────────────────────────────────────────────────────────────────────┐
│  Формат                                              [Записать] [Закрыть]│
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Код:         [000000001]                                               │
│  Наименование:[Формат остатка на счёте                            ]    │
│                                                                          │
│  JSON схема:                                                             │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │ {                                                                  │ │
│  │   "остаток": 1500000.50,                                          │ │
│  │   "валюта": "RUB",                                                │ │
│  │   "счёт": "40702810100000000001",                                 │ │
│  │   "дата": "2026-01-23"                                            │ │
│  │ }                                                                  │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

## Примеры форматов

### Простой формат

```json
{
  "результат": "значение"
}
```

### Формат с числовыми данными

```json
{
  "остаток_дней": 14,
  "использовано_дней": 10,
  "всего_дней": 24
}
```

### Формат со списком

```json
{
  "счета": [
    {
      "номер": "001",
      "сумма": 50000,
      "дата": "2026-01-15"
    },
    {
      "номер": "002",
      "сумма": 75000,
      "дата": "2026-01-20"
    }
  ],
  "итого": 125000
}
```

### Формат с вложенными объектами

```json
{
  "сотрудник": {
    "фио": "Иванов И.И.",
    "должность": "Менеджер",
    "отдел": "Продажи"
  },
  "отпуск": {
    "дата_начала": "2026-02-01",
    "дата_окончания": "2026-02-14",
    "дней": 14
  }
}
```

## Использование формата

### В инструменте

1. Откройте инструмент
2. Выберите формат в поле "Формат"
3. Убедитесь, что код инструмента возвращает данные в этом формате

```
┌─────────────────────────────────────────────────────────────────────────┐
│  Инструмент: Получить остаток на счёте                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Формат: [Формат остатка на счёте                                 ▼]   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

### В коде инструмента

```bsl
// Код инструмента должен возвращать структуру, соответствующую формату

Результат = Новый Структура;
Результат.Вставить("остаток", ОстатокНаСчёте);
Результат.Вставить("валюта", "RUB");
Результат.Вставить("счёт", НомерСчёта);
Результат.Вставить("дата", Формат(ТекущаяДата(), "ДФ=yyyy-MM-dd"));
```

## Создание формата

### Шаг 1: Определение структуры

Определите, какие данные возвращает инструмент:

| Поле    | Тип    | Описание           |
| ------- | ------ | ------------------ |
| остаток | number | Сумма остатка      |
| валюта  | string | Код валюты         |
| дата    | string | Дата в формате ISO |

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

Создайте пример JSON:

```json
{
  "остаток": 0,
  "валюта": "",
  "дата": ""
}
```

### Шаг 3: Сохранение

1. Откройте справочник "Форматы"
2. Создайте новый элемент
3. Введите наименование
4. Вставьте JSON схему
5. Сохраните

## Типы данных в JSON

| Тип       | Пример           | Описание        |
| --------- | ---------------- | --------------- |
| `string`  | `"текст"`        | Строка          |
| `number`  | `123.45`         | Число           |
| `integer` | `42`             | Целое число     |
| `boolean` | `true` / `false` | Логическое      |
| `array`   | `[1, 2, 3]`      | Массив          |
| `object`  | `{"a": 1}`       | Объект          |
| `null`    | `null`           | Пустое значение |

## Рекомендации

### Именование полей

* Используйте понятные имена
* Используйте snake\_case или кириллицу
* Будьте последовательны

**Хорошо:**

```json
{
  "остаток_дней": 14,
  "дата_начала": "2026-02-01"
}
```

**Плохо:**

```json
{
  "d": 14,
  "dt1": "2026-02-01"
}
```

### Структура данных

* Группируйте связанные поля
* Используйте массивы для списков
* Избегайте слишком глубокой вложенности

### Документирование

Добавляйте комментарии в наименование формата:

```
Наименование: Формат списка счетов (массив объектов с номером, суммой, датой)
```

## Устранение проблем

### Инструмент возвращает неверный формат

1. Проверьте код инструмента
2. Убедитесь, что возвращается структура, а не строка
3. Проверьте типы данных

### LLM неправильно интерпретирует данные

1. Упростите формат
2. Добавьте описания полей в описание инструмента
3. Используйте понятные имена полей

## Далее

{% content-ref url="/pages/axcAjQLvtdkQ1bPfMSRB" %}
[MCP серверы](/ai-platforma-oneapa/spravochniki/mcp-servery.md)
{% endcontent-ref %}