# Компоненты

Платформа 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) — начало работы с системой


---

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