> 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/obzor-sistemy/komponenty.md).

# Компоненты

Платформа OneAPA состоит из нескольких взаимосвязанных компонентов. В этом разделе подробно описан каждый из них.

## Расширение для 1С

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

Расширение является центральным компонентом системы, обеспечивающим:

* Хранение настроек агентов, инструментов и моделей
* Пользовательский интерфейс (чат)
* Выполнение инструментов (запросы к данным, бизнес-логика)
* Интеграцию с другими подсистемами 1С

### Интеграция с существующей базой

Конфигурация OneAPA может быть объединена с любой конфигурацией 1С:

```
┌─────────────────────────────────────────────────┐
│           Ваша конфигурация 1С                  │
│  ┌─────────────┐  ┌─────────────┐              │
│  │ Бухгалтерия │  │     ERP     │              │
│  └─────────────┘  └─────────────┘              │
│                                                 │
│  ┌─────────────────────────────────────────┐   │
│  │           Расширение OneAPA              │   │
│  │   (или объединённая конфигурация)        │   │
│  └─────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘
```

## Python Proxy Server

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

Proxy-сервер обеспечивает:

* Взаимодействие с LLM провайдерами
* Оркестрацию workflow агентов
* Web-интерфейс чата
* REST API для внешних систем

### Технологический стек

| Технология    | Версия | Назначение            |
| ------------- | ------ | --------------------- |
| **Python**    | 3.11+  | Язык программирования |
| **FastAPI**   | latest | REST API framework    |
| **LangGraph** | latest | Оркестрация workflow  |
| **LangChain** | latest | Интеграция с LLM      |
| **Chainlit**  | latest | Web UI для чата       |
| **Pydantic**  | latest | Валидация данных      |
| **uvicorn**   | latest | ASGI сервер           |

### Структура файлов

```
OneAPAProxy/
├── main.py              # Точка входа, запуск сервера
├── api.py               # REST API endpoints
├── agent_logic.py       # Логика агентов (LangGraph)
├── graph_init.py        # Инициализация графа workflow
├── llm_utils.py         # Утилиты для работы с LLM
├── models.py            # Pydantic модели данных
├── data_store.py        # Хранилище данных
├── cl_main.py           # Chainlit UI
├── logging_config.py    # Конфигурация логирования
├── requirements.txt     # Зависимости Python
├── Dockerfile           # Docker образ
└── rebuild-container.ps1 # Скрипт пересборки контейнера
```

### REST API

#### GET /health

Проверка работоспособности сервера.

**Ответ:**

```json
{
  "message": "OK",
  "version": "1.0.1",
  "build_date": "2025-12-03"
}
```

#### POST /load

Загрузка агентов и инструментов из 1С.

**Тело запроса:**

```json
{
  "agents": [
    {
      "agent": {
        "id": "agent-001",
        "name": "Кадровый агент",
        "model": {
          "service": "OpenAI",
          "token": "sk-...",
          "folder": "gpt-4o",
          "url": ""
        },
        "infobase": "my_base",
        "description": "Агент для кадровых вопросов",
        "systemprompt": "Ты кадровый специалист...",
        "userprompt": "",
        "tools": [...],
        "mcps": [...]
      }
    }
  ],
  "toolsendpoint": "http://localhost/hs/oneapa/tools"
}
```

#### POST /chat

Отправка сообщения агенту.

**Тело запроса:**

```json
{
  "message": "Сколько у меня отпускных дней?",
  "files": [
    {
      "content": "base64_encoded_content",
      "name": "document.pdf"
    }
  ]
}
```

**Ответ:**

```json
{
  "response": "У вас осталось 14 дней отпуска.",
  "tool_results": [
    {
      "tool": "get_vacation_days",
      "result": {"days": 14}
    }
  ]
}
```

### LangGraph Workflow

```
                    ┌─────────────┐
                    │    START    │
                    └──────┬──────┘
                           │
                           ▼
                    ┌─────────────┐
              ┌─────│   router    │─────┐
              │     └─────────────┘     │
              ▼                         ▼
       ┌─────────────┐          ┌─────────────┐
       │    agent    │          │   fallback  │
       └──────┬──────┘          └──────┬──────┘
              │                        │
              ▼                        │
       ┌─────────────┐                 │
       │decide_next  │                 │
       └──────┬──────┘                 │
              │                        │
    ┌─────────┼─────────┐              │
    ▼         ▼         ▼              │
┌───────┐ ┌───────┐ ┌───────┐          │
│ tools │ │ agent │ │  END  │◄─────────┘
└───┬───┘ └───────┘ └───────┘
    │         ▲
    └─────────┘
```

**Узлы графа:**

| Узел             | Назначение                                  |
| ---------------- | ------------------------------------------- |
| **router**       | Выбор агента для обработки запроса          |
| **agent**        | Вызов LLM для анализа и формирования ответа |
| **tools**        | Выполнение инструментов                     |
| **fallback**     | Обработка ошибок                            |
| **decide\_next** | Решение о следующем шаге (tools/agent/END)  |

## Chainlit Web UI

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

Веб-интерфейс для взаимодействия с агентами через браузер.

### Функциональность

* Чат-интерфейс с историей сообщений
* Поддержка файлов (изображения, документы)
* Отображение процесса работы агента
* Сессии пользователей

### Доступ

По умолчанию доступен по адресу: `http://<proxy-server>:9000/ui`

```
┌─────────────────────────────────────────────────┐
│  OneAPA Chat                              [—][□][×] │
├─────────────────────────────────────────────────┤
│                                                 │
│  [Агент]: Здравствуйте! Чем могу помочь?       │
│                                                 │
│  [Вы]: Сколько дней отпуска у меня осталось?   │
│                                                 │
│  [Агент]: Проверяю...                          │
│  📊 Вызываю инструмент: get_vacation_days      │
│                                                 │
│  [Агент]: У вас осталось 14 дней отпуска.      │
│                                                 │
├─────────────────────────────────────────────────┤
│  [Введите сообщение...]              [📎][Send] │
└─────────────────────────────────────────────────┘
```

## MCP серверы

### Что такое MCP

**Model Context Protocol (MCP)** — открытый протокол для взаимодействия LLM с внешними инструментами и данными.

### OneAPA как MCP сервер

OneAPA предоставляет свои инструменты как MCP сервер:

```
┌─────────────────┐         ┌─────────────────┐
│   MCP клиент    │ ◄─────► │  OneAPA         │
│   (Cursor,      │   MCP   │  MCP Server     │
│    Claude,      │         │                 │
│    другие)      │         │                 │
└─────────────────┘         └─────────────────┘
```

### OneAPA как MCP клиент

OneAPA может использовать внешние MCP серверы:

```
┌─────────────────┐         ┌─────────────────┐
│   OneAPA        │ ◄─────► │  Внешний        │
│   MCP Client    │   MCP   │  MCP Server     │
│                 │         │  (filesystem,   │
│                 │         │   github, etc)  │
└─────────────────┘         └─────────────────┘
```

## Интеграция с OneRPA

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

Модуль APA\_OneRPA позволяет запускать роботов OneRPA как инструменты агента.

### Сценарий использования

```
Пользователь: "Загрузи данные из Excel файла sales.xlsx"

Агент → анализ запроса
      → выбор инструмента "запустить_робота_загрузки"
      → вызов OneRPA с параметрами
      → получение результата
      → формирование ответа

Агент: "Данные из sales.xlsx успешно загружены. Добавлено 150 строк."
```

### Конфигурация

В справочнике APA\_Инструменты:

* **OneRPA** — флаг, указывающий на инструмент OneRPA
* **КодЗаданияOneRPA** — код задания для запуска

## Система логирования

### Уровни логирования

| Уровень | Описание                        |
| ------- | ------------------------------- |
| DEBUG   | Детальная отладочная информация |
| INFO    | Общая информация о работе       |
| WARNING | Предупреждения                  |
| ERROR   | Ошибки                          |

### Логирование в 1С

Регистр **APA\_ЛогИнструментов**:

| Измерение  | Тип          | Описание             |
| ---------- | ------------ | -------------------- |
| Инструмент | Справочник   | Ссылка на инструмент |
| Дата       | ДатаВремя    | Время выполнения     |
| Состояние  | Перечисление | Успешно/Ошибка       |
| Результат  | Строка       | Результат выполнения |

## Далее

* [Ключевые возможности](/ai-platforma-oneapa/obzor-sistemy/klyuchevye-vozmozhnosti.md) — функциональность платформы
* [Быстрый старт](/ai-platforma-oneapa/bystryj-start.md) — начало работы с системой