Агент oData в чате: мультиагентный чат-бот для 1С

Агент OData в чате: мультиагентный чат-бот для 1С

Open-source проект для запросов к данным 1С через естественный язык — с AI-агентами, MCP-сервером и внешними обработками.

Задача

Задача — дать пользователю AI-ассистента, привязанного к его данным в базе 1С. Не абстрактный чат-бот, а помощник, который знает структуру вашей конфигурации, понимает названия справочников и документов на русском языке и может вернуть конкретные данные — список контрагентов, сумму реализаций, количество сотрудников.

Почему это нетривиально? 1С предоставляет стандартный OData-интерфейс с версии платформы 8.3.6, который открывает доступ ко всем данным через HTTP. Но сформировать правильный OData-запрос — это интеллектуальная задача:

• Нужно знать, что «сотрудники» — это Catalog_Сотрудники, а «реализация» — Document_РеализацияТоваровУслуг.
• URL содержит кириллицу, которую нужно кодировать: %D0%A1%D0%BE%D1%82%D1%80....
• Ссылочные поля возвращают GUID — без $expand получаешь Контрагент_Key: a1b2c3d4-....
• Фильтры, подсчёты, сортировки — каждый запрос уникален: $filter=contains(Description,'Иванов') and DeletionMark eq false.
• Вариантов запросов — бесконечное множество, и каждый зависит от того, что именно хочет узнать пользователь.

А бесконечное количество вариантов интеллектуальной задачи — это как раз то, что хорошо делает AI.

Решение

Поручить формирование OData-запросов искусственному интеллекту. Пользователь пишет вопрос на русском языке, AI определяет нужный объект 1С, формирует запрос, выполняет его и возвращает человекочитаемый ответ. Всё — в чате.

Получился проект 1c-oData-skill — https://github.com/gybson63/1c-oData-skill.

Что внутри

Проект состоит из четырёх компонентов:

Сейчас бот работает через Telegram, но архитектура рассчитана на подключение других мессенджеров.

Демо: от вопроса к данным

Пользователь пишет в Telegram:

Покажи последних 5 контрагентов

Бот отвечает:

Контрагенты (5):
• ООО «Ромашка» (код 000123)
• ИП Иванов Иван Иванович
• АО «Рога и Копыта»
• ООО «Поставщик»
• ИП Петров Пётр Петрович

Всего: 5

Что произошло под капотом:

1. AI-агент распознал намерение: показать справочник «Контрагенты», лимит 5.
2. Сформировал OData-запрос: GET Catalog_Контрагенты?$top=5&$orderby=Description asc&$format=json.
3. Выполнил HTTP-запрос к 1С через MCP-сервер.
4. Второй AI-агент отформатировал JSON в красивый ответ для Telegram.

Ещё примеры

Пользователь: Сколько сотрудников в базе?

Бот: Всего сотрудников: 1 234

Пользователь: Документы реализации за май

Бот: Реализация товаров и услуг (12):
• №УТ-000123 от 02.05.2026 — ООО «Покупатель» — 150 000 р.
• №УТ-000122 от 05.05.2026 — ИП Сидоров — 43 200 р.
...
Всего: 12

Пользователь: а за апрель?

Бот: Реализация товаров и услуг (8):
• №УТ-000098 от 03.04.2026 — АО «Заказчик» — 210 000 р.
...
Всего: 8

Бот помнит контекст диалога — уточнение «а за апрель?» понимается как «документы реализации за апрель».

Архитектура

Бот построен на мультиагентной модели. Каждый агент — независимый модуль, наследующий BaseAgent:

BaseAgent (абстрактный класс)
+------ ODataAgent — запросы к 1С через OData
+------ FormatterAgent — форматирование ответов для Telegram

Двухшаговая обработка

Ключевой паттерн — разделение на два шага.

Шаг 1: ODataAgent

• Получает вопрос пользователя.
• Через tool calling / function calling вызывает MCP-инструменты.
• AI определяет: какой объект 1С нужен, какие фильтры, какие поля.
• Формирует OData-запрос и выполняет его.
• Возвращает «сырой» результат.

Шаг 2: FormatterAgent

• Получает JSON от ODataAgent.
• Форматирует в HTML для Telegram.
• Скрывает служебные поля: Ref_Key, DataVersion, DeletionMark и другие.
• Подставляет наименования вместо GUID.
• Добавляет разделители тысяч, форматирует даты.

MCP-клиент

Бот поддерживает подключение внешних MCP-серверов Model Context Protocol через два транспорта:

• stdio — запуск сервера как подпроцесса, основной способ.
• SSE — подключение к удалённому серверу по HTTP.

MCP-сервер предоставляет AI-агенту инструменты:

• Выполнение HTTP-запросов к OData API: GET, POST, PATCH, DELETE.
• Получение метаданных $metadata.
• Справочник типов объектов 1С.

Автоматический фоллбэк

Если модель AI не поддерживает tool calling, бот автоматически переключается на текстовый режим: формирует промпт с инструкциями по OData и передаёт его как обычный чат.

Расширяемость

Добавить нового агента — три шага.

1. Создать класс, унаследовав BaseAgent:

   from bot.agents.base import BaseAgent
   
   class MyAgent(BaseAgent):
       name = "my_agent"
   
       async def process_message(self, user_text, history):
           # логика обработки
           return answer, history

2. Зарегистрировать в bot.py:

   AGENT_REGISTRY = {
       "odata": ODataAgent,
       "my_agent": MyAgent,
   }

3. Добавить секцию в env.json.

Настройка и запуск

Требования

• 1С:Предприятие 8.3.6+ с опубликованным OData-интерфейсом.
• Python 3.10+.
• Аккаунт AI-провайдера: OpenAI, YandexGPT или любой OpenAI-совместимый API.

Шаг 1. Опубликовать OData в 1С

Если OData уже опубликован — пропустите. Если нет:

• Вариант А: через Конфигуратор — Администрирование U94; Публикация на веб-сервере U94; отметить «Публиковать стандартный интерфейс OData».
• Вариант Б: через EPF-обработку из проекта. Подробнее — ниже, в разделе про EnableODataInterface.

Шаг 2. Установить зависимости

git clone https://github.com/gybson63/1c-oData-skill.git
cd 1c-oData-skill
pip install -r requirements.txt

Зависимости минимальные:

python-telegram-bot>=20.0
openai>=1.0.0
mcp>=1.0.0
httpx>=0.27.0

Шаг 3. Настроить конфигурацию

cp env.example.json env.json

Заполнить env.json:

{
  "profiles": {
    "default": {
      "telegram_token": "123456:ABC-DEF...",
      "ai_api_key": "sk-...",
      "ai_base_url": "https://api.openai.com/v1",
      "ai_model": "gpt-4o-mini",
      "ai_rpm": 20,
      "agents": {
        "odata": {
          "type": "odata",
          "odata_url": "http://localhost/YourBase/odata/standard.odata",
          "odata_user": "Администратор",
          "odata_password": "пароль",
          "mcp_servers": {
            "odata": {
              "command": "python",
              "args": ["mcp_servers/odata_server.py"],
              "env": {
                "ODATA_URL": "http://localhost/YourBase/odata/standard.odata",
                "ODATA_USER": "Администратор",
                "ODATA_PASSWORD": "пароль"
              }
            }
          }
        }
      },
      "formatter": {
        "enabled": true,
        "formatter_model": "gpt-4o-mini"
      }
    }
  }
}

Поддерживаемые AI-модели

Шаг 4. Запустить

python -m bot

С параметрами:

python -m bot --env-file env.json --profile default --log-level DEBUG

Docker

docker-compose up -d

MCP-сервер: интеграция с ИИ-агентами

Помимо Telegram-бота, в проект входит готовый MCP-сервер — его можно подключить к любому ИИ-агенту, поддерживающему Model Context Protocol: Cline, Claude Desktop, Cursor, VS Code Copilot.

Подключение

Добавить в конфигурацию MCP-клиента:

{
  "mcpServers": {
    "1c-odata": {
      "command": "python",
      "args": ["mcp_servers/odata_server.py"],
      "env": {
        "ODATA_URL": "http://localhost/YourBase/odata/standard.odata",
        "ODATA_USER": "Администратор",
        "ODATA_PASSWORD": "пароль"
      }
    }
  }
}

После этого ИИ-агент получает возможность выполнять OData-запросы к вашей базе 1С напрямую из IDE. Например, в VS Code с расширением Cline можно написать: «Покажи список организаций из 1С» — и агент сам сформирует и выполнит запрос.

Сервер поддерживает GET, POST, PATCH, DELETE — полный набор CRUD-операций.

Практические примеры

Подсчёт записей

Пользователь: Сколько документов реализации за май?

AI формирует:

GET Document_РеализацияТоваровУслуг/$count?$filter=Date ge datetime'2026-05-01T00:00:00' and Date lt datetime'2026-06-01T00:00:00'

Бот: Документов реализации за май: 47

Поиск по наименованию

Пользователь: Найди контрагента ООО Ромашка

AI формирует:

GET Catalog_Контрагенты?$filter=contains(Description,'Ромашка')&$top=10

Бот:

Найдено контрагентов: 2
• ООО «Ромашка» (код 000145)
• ООО «Ромашка Плюс» (код 000289)

Документы с раскрытием ссылок

Пользователь: Последние 5 реализаций

AI формирует:

GET Document_РеализацияТоваровУслуг?$top=5&$orderby=Date desc&$expand=Контрагент

Бот:

Реализация товаров и услуг (5):
• №УТ-000123 от 15.05.2026 — ООО «Покупатель» — 150 000 р.
• №УТ-000122 от 14.05.2026 — ИП Сидоров — 43 200 р.
• №УТ-000121 от 13.05.2026 — АО «Ромашка» — 12 500 р.
• №УТ-000120 от 12.05.2026 — ООО «Клиент» — 89 000 р.
• №УТ-000119 от 11.05.2026 — ИП Кузнецов — 5 400 р.

Всего: 5

Контрагент показан наименованием, а не GUID — благодаря $expand и форматтеру.

Фильтрация по реквизитам

Пользователь: Покажи сотрудников отдела продаж

AI формирует:

GET Catalog_Сотрудники?$filter=Подразделение/Description eq 'Отдел продаж'&$expand=Подразделение

Под капотом: для разработчика

Structured logging

Два формата вывода одновременно:

Ротация по дате, автоочистка файлов старше 30 дней, фильтр дедупликации повторяющихся ошибок.

Метрики и учёт затрат

In-memory реестр метрик:

• Счётчики — запросы, ошибки, попадания в кэш.
• Таймеры — min/max/avg время операций.
• AI Usage — токены и стоимость по моделям.

CostLogger пишет AI-затраты в JSONL-файлы — один файл на день:

{"ts": "2026-05-04T12:00:00+04:00", "model": "gpt-4o-mini", "input_tokens": 1000, "output_tokens": 500, "cost_usd": 0.00045, "chat_id": 123456}

CostAnalyzer агрегирует по интервалам:

analyzer = CostAnalyzer("logs/costs")
print(analyzer.summary("day"))  # Дневная сводка
print(analyzer.total_cost())    # Общая сумма

Учёт токенов по сессиям

После каждого ответа бот показывает компактную строку:

📊 📥3,200 📤1,500 | 💰S81;2.15

Команда /tokens — детальный отчёт по текущей сессии.

Настройка терминологии

Файл bot/config_hint.md — словарь бизнес-терминов вашей конфигурации. Для ЗУП это: «сотрудники U94; Catalog_Сотрудники», «отпуск U94; Document_ЗаявкаНаОтпуск», «больничный U94; Document_БольничныйЛист». Для УТ — свои термины. AI читает этот файл и понимает, что имеет в виду пользователь.

EPF-обработка: EnableODataInterface

Чтобы бот мог работать с данными, объекты 1С должны быть опубликованы через OData. Обычно это делается через Конфигуратор — но не у всех есть к нему доступ, и не всегда это удобно.

В проект входит внешняя обработка EnableODataInterface.epf — она запускается прямо из режима Предприятия и позволяет управлять составом объектов OData:

• При открытии — читает текущий состав OData и расставляет флажки.
• Отметил нужные объекты, нажал «Применить» — обработка вызывает УстановитьСоставСтандартногоИнтерфейсаOData().
• Исходники обработки включены в проект XML, сборка EPF — через PowerShell-скрипт.

Telegram-команды

Стек технологий

Лицензия: MIT — используйте свободно.

Итоги

Что умеет проект

• Запросы к данным 1С на естественном языке через Telegram.
• Мультиагентная архитектура: ODataAgent + FormatterAgent.
• MCP-сервер для интеграции с ИИ-агентами: Cline, Claude Desktop, Cursor.
• Поддержка любой OpenAI-совместимой модели: OpenAI, YandexGPT, Ollama.
• EPF-обработка для управления составом OData без Конфигуратора.
• Structured logging, метрики, учёт AI-затрат.
• Docker-деплой.

Что в планах

• 🔜 Поддержка других мессенджеров: Max
• 🔜 WebSocket-транспорт для MCP.
• 🔜 Web UI.
• 🔜 Новые агенты: аналитика, генерация отчётов.

Репозиторий: https://github.com/gybson63/1c-oData-skill

Звёздочки на GitHub, issue с багами и идеи в обсуждениях — приветствуются!