Подключение RAGRAF к SagaAI

Платформа SagaAI

Открытая платформа для команды ИИ-сотрудников: чат-ассистенты, автономные оркестраторы, базы знаний (RAG) и встроенный агент-разработчик DevAgent — в одном веб-интерфейсе (Streamlit), на своём компьютере или сервере. Лицензия MIT; линия 1.x сохраняет публичные API, интерфейс и форматы данных обратно совместимыми. Интерфейс — на русском, английском и китайском. Все факты этого гайда проверены по коду репозитория TVD2100/sagaai-platform (v1.13.1).

Установка и запуск

Платформа — обычное Python-приложение: зависимости из requirements.txt (streamlit, requests, sqlalchemy, cryptography; опционально парсеры документов и paramiko для SSH), запуск через streamlit run app.py. Если команда не находит streamlit — python -m streamlit run app.py. После запуска задайте API-ключи сервисов на странице «Настройки».

git clone https://github.com/TVD2100/sagaai-platform SagaAI
cd SagaAI
pip install -r requirements.txt
streamlit run app.py        # → http://localhost:8501

Как подключается RAGRAF

Почему это работает

run_code — «универсальный запасной выход» платформы: установка пакетов, выполнение shell-команд и скриптов, любые операции, для которых нет специализированного инструмента. CLI RAGRAF (tools/ragraf.py) — обычный Python-скрипт: агент вызывает его так же, как в любой оболочке, и читает текст ответа сам — интерпретировать JSON-RPC-схему не нужно. Навык ragraf-core задаёт порядок: сначала ensure, затем операции индекса вместо чтения файлов.

RAGRAF не заменяет встроенные базы знаний SagaAI и не конфликтует с ними: базы платформы ищут по документам (bm25/vector/hybrid), RAGRAF — граф фактов о коде (символы, связи, ревизии, свежесть индекса, контроль записи). Сотрудник может опираться на оба источника: документы — через rag_search, код — через CLI RAGRAF.

Подключение — четыре шага

1. 1Установите RAGRAF и постройте корпусСтандартная установка RAGRAF (install.ps1 или pip -e .), затем ensure на каталог проекта. Корпус один на всех сотрудников: индекс открывается агентами read-only, несколько диалогов и оркестраторов работают с ним одновременно.
2. 2Установите навык ragraf-core в библиотекуСтраница библиотеки навыков → установка из GitHub-URL, ZIP-архива или локальной папки (реестр skills/skills.json в каталоге данных; лимиты: 200 МБ на архив, 5000 файлов, 50 МБ на файл, распаковка защищена от path traversal). Сторонний навык получает developer=unknown, adapted=False и НЕ попадает в блок Available skills системного промпта, пока адаптация не завершена: кнопка «Адаптировать» передаёт задачу DevAgent (Skill Developer), по завершении он вызывает mark_skill_adapted.
3. 3Внесите регламент в инструкцииУниверсальный фрагмент AGENTS.md (страница «Интеграции») добавьте в инструкцию оркестратора (инструкции сохраняются между перезапусками) или в AGENT.md проекта — DevAgent ведёт этот файл и читает его при работе в рабочей папке. Порядок «спроси индекс → проверь конверт → write_check перед записью» обязателен: без регламента агенты возвращаются к search_in_files, и это сразу видно в статистике вызовов RAGRAF.
4. 4Проверьте вызовом в диалогеПопросите сотрудника выполнить через run_code: catalog (ожидается список корпусов), затем ensure <каталог> (ожидается status: actual). Файлы навыка агент читает инструментом get_skill_file — workspace-инструменты (read_file, verify_file) пути вне проекта отклоняют: «Path escapes project root».

# инструменты агента (run_code) вызывают CLI RAGRAF как обычную команду:
python <repo>\tools\ragraf.py catalog
python <repo>\tools\ragraf.py ensure <каталог проекта>
python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml query symbol --name <имя>
python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml check
python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml usage --agent saga-worker

Безопасность платформы

Что проверено в коде v1.13.1 — эти механизмы определяют, как именно агент будет работать с RAGRAF:

• run_code выполняет произвольный код в изолированном subprocess (таймаут 300 с, run_test — 180 с); код с опасными паттернами (деструктивные команды, изменение системы, сетевые операции) блокируется до явного подтверждения пользователем в UI.
• Защита от path traversal: инструменты не выходят за пределы рабочей папки; активная папка привязана к диалогу и восстанавливается при его открытии.
• Недоверенные данные размечаются (санитизация результатов, метка [DATA_FROM_WEB_SEARCH]), эвристическая защита от prompt-injection.
• API-ключи хранятся в защищённом виде (или задаются переменными окружения и не сохраняются в БД); TLS-верификация включена по умолчанию; секреты не отображаются в интерфейсе.
• Правки DevAgent версионируются: бэкапы файлов, снапшоты проекта и полный откат — действия агента обратимы.

Телеметрия

Каждый вызов CLI давайте с --agent <имя сотрудника> (saga-worker, saga-reviewer, …): usage_call разделит профили вызовов по агентам при общем kind=external. Здоровый профиль — доминирование symbol/search/write_check и ноль полных чтений файлов. Сверяйте со страницей «Статистика» платформы (расход токенов по периодам, поставщикам и моделям): экономия на навигации по коду видна по обеим метрикам.

Задел на MCP

Если в платформе появится MCP-клиент, контракт RAGRAF не изменится: stdio-сервер, JSON-RPC, 24 инструмента ragraf_*. Достаточно зарегистрировать запуск — конфиг ниже. --project можно не указывать: корпус определится по рабочему каталогу через реестр разработок, переключение на чужой проект — инструментом ragraf_use_project.

{
  "mcpServers": {
    "ragraf": {
      "command": "python",
      "args": [
        "<repo>/tools/ragraf-mcp.py",
        "--agent", "saga-worker",
        "--agent-kind", "external"
      ]
    }
  }
}

Факты платформы верифицированы по коду github.com/TVD2100/sagaai-platform (v1.13.1, MIT): поиск MCP-клиента, каталог инструментов (dev_agent/tool_executor.py, universal_agent.py), библиотека навыков (core/skills_library.py), правила подтверждения (core/dangerous.py), README и AGENT.md. Связка RAGRAF × SagaAI описана по механизмам платформы; замер живой сессии не проводился — в отличие от AutoClaw и DeepSeek Harness.