Connecting RAGRAF to SagaAI

The SagaAI platform

An open platform for a team of AI employees: chat assistants, autonomous orchestrators, knowledge bases (RAG) and the built-in DevAgent developer agent — in a single web interface (Streamlit), on your own computer or server. MIT license; the 1.x line keeps its public APIs, interface and data formats backward compatible. The interface is available in Russian, English and Chinese. Every fact in this guide was verified against the code of the TVD2100/sagaai-platform repository (v1.13.1).

Install and run

The platform is an ordinary Python application: dependencies from requirements.txt (streamlit, requests, sqlalchemy, cryptography; optional document parsers and paramiko for SSH), launched with streamlit run app.py. If the command cannot find streamlit — python -m streamlit run app.py. After the start, set the service API keys on the Settings page.

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

How RAGRAF connects

Why this works

run_code is the platform universal escape hatch: installing packages, running shell commands and scripts, any operation without a dedicated tool. The RAGRAF CLI (tools/ragraf.py) is an ordinary Python script: the agent calls it exactly as in any shell and reads the response text itself — no JSON-RPC schema interpretation needed. The ragraf-core skill sets the order: ensure first, then index operations instead of reading files.

RAGRAF does not replace the built-in SagaAI knowledge bases and does not conflict with them: platform bases search documents (bm25/vector/hybrid), RAGRAF is a graph of code facts (symbols, relations, revisions, index freshness, write control). An employee can rely on both: documents via rag_search, code via the RAGRAF CLI.

Connection — four steps

1. 1Install RAGRAF and build the corpusStandard RAGRAF installation (install.ps1 or pip -e .), then ensure on the project directory. One corpus for every employee: the index is opened read-only by agents, several dialogs and orchestrators work with it at the same time.
2. 2Install the ragraf-core skill into the librarySkills library page → install from a GitHub URL, ZIP archive or local folder (skills/skills.json registry in the data directory; limits: 200 MB per archive, 5000 files, 50 MB per file, extraction protected against path traversal). A third-party skill gets developer=unknown, adapted=False and does NOT reach the Available skills block of the system prompt until adaptation completes: the "Adapt" button hands the task to DevAgent (Skill Developer), who calls mark_skill_adapted when done.
3. 3Put the regimen into instructionsAdd the universal AGENTS.md fragment (Integrations page) to an orchestrator instruction (instructions persist across restarts) or to the project AGENT.md — DevAgent maintains that file and reads it when working in the workspace. The order "ask the index → check the envelope → write_check before any write" is mandatory: without a regimen agents fall back to search_in_files, immediately visible in the RAGRAF call statistics.
4. 4Verify with a call in a dialogAsk the employee to run via run_code: catalog (expect the corpus list), then ensure <directory> (expect status: actual). The agent reads skill files with get_skill_file — workspace tools (read_file, verify_file) reject paths outside the project: "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

Platform security

Verified in the v1.13.1 code — these mechanisms define how exactly the agent will work with RAGRAF:

• run_code executes arbitrary code in an isolated subprocess (300 s timeout, run_test — 180 s); code with dangerous patterns (destructive commands, system modification, network operations) is blocked until the user explicitly confirms it in the UI.
• Path traversal protection: tools never leave the working folder; the active folder is bound to the dialog and restored when it is reopened.
• Untrusted data is marked (result sanitization, the [DATA_FROM_WEB_SEARCH] tag), heuristic prompt-injection protection.
• API keys are stored securely (or set via environment variables and never saved to the DB); TLS verification is on by default; secrets are not displayed in the interface.
• DevAgent edits are versioned: file backups, project snapshots and full rollback — agent actions are reversible.

Telemetry

Pass --agent <employee name> (saga-worker, saga-reviewer, …) with every CLI call: usage_call splits call profiles per agent under the shared kind=external. A healthy profile is symbol/search/write_check dominating and zero full file reads. Cross-check with the platform Statistics page (token usage by period, provider and model): the navigation savings show in both metrics.

MCP outlook

If an MCP client appears in the platform, the RAGRAF contract will not change: stdio server, JSON-RPC, 24 ragraf_* tools. Registering the launch is enough — config below. --project can be omitted: the corpus is resolved from the working directory through the development registry, switching to another project is the ragraf_use_project tool.

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

Platform facts verified against the code of github.com/TVD2100/sagaai-platform (v1.13.1, MIT): MCP-client search, tool catalogs (dev_agent/tool_executor.py, universal_agent.py), the skills library (core/skills_library.py), confirmation rules (core/dangerous.py), README and AGENT.md. The RAGRAF × SagaAI pairing is described from platform mechanisms; no live session was measured — unlike AutoClaw and DeepSeek Harness.