# Форматы

Справочник `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 %}


---

# 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/formaty.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.