OntoAgents

Build agents. Build their ontologies. Self-hosted.

English | 简体中文

OntoAgents is a personal work & learning assistant for knowledge-intensive professionals (engineers, teachers, compliance officers, researchers, clinicians) — fully deployable on one machine. Its thesis: your knowledge should not be a pile of documents, but a structured asset you can query, audit and quiz against — an ontology. Built with Go (CloudWeGo Eino/ADK), React and SQLite, it is organized around two cores:

• Agent engineering — a conversational agent workbench with fully observable execution, multi-agent collaboration, and knowledge / skill / ontology augmentation.
• Ontology engineering — a full ontology (knowledge-graph) lifecycle: build → asset management → runtime engines → consumption & audit.

Self-hosted — data, keys and knowledge stay under your control: data lives in a local SQLite database, model API keys are AES-256-GCM encrypted on disk, and the only external dependency is the LLM provider(s) you configure.

Contents

• ✨ Key Features
• 🧭 Explore
• 🚀 Quick Start
• 💻 Development Mode
• 🧱 Tech Stack
• 🗂 Repository Layout
• 📚 Documentation
• 🧭 Roadmap
• 🙏 Open Source & Papers
• ❓ FAQ
• 🤝 Contributing
• 📜 License

✨ Key Features

• Fully observable execution — tool calls, thinking, sub-agent delegation, knowledge recall and ontology queries appear as color-coded event cards; export & replay make every answer accountable.
• Multi-agent collaboration — Agent-as-Tool / Transfer orchestration with a visible delegation timeline; a 2–4-pane comparison mode runs one question under different configurations side by side.
• Ontology as the knowledge backbone — build → assets → runtime → consumption & audit; answers trace back to structured knowledge, not text scraps.
• AI-assisted building behind quality gates — six build paths (manual, OntoChat conversational authoring, CQ-driven evolution, build-from-KB, CSV, import/merge); LLM output enters the library only after scoring and self-repair.
• CQ regression baselines — competency questions become re-runnable test assets: coverage quantification plus an answerability pre-check (check_answerable).
• RAG + GraphRAG knowledge bases — vector retrieval plus a self-contained KG backend (graph browsing / multi-hop / community QA); a companion ontology grows with every conversation.
• Open by protocol — every agent is itself an MCP server; MCP + A2A connect external agents; execution backends are pluggable (in-process / Docker / Kubernetes).
• Single-machine & desktop — one command to start, zero Python runtime dependency; Windows / macOS installers; data, keys and ontologies never leave the machine.

Each point unfolds below in Explore; module-level guides live in docs/handbook/.

🧭 Explore

Agent engineering: a fully observable conversation workbench

• Every step of execution is visible — on top of SSE streaming replies, tool calls, deep thinking, sub-agent delegation, knowledge recall and ontology queries appear as color-coded event cards; expandable JSON, raw-event debugging, export & replay — every answer is accountable.
• Multi-agent collaboration — projects orchestrate multiple agents (Agent-as-Tool / Transfer) with a visible delegation timeline; a 2–4 pane comparison mode runs the same question under different configurations (model / knowledge base / ontology / skill / temperature / prompt override) side by side.
• Knowledge · skill · ontology augmentation — document upload → chunking → embedding → retrieval, with a GraphRAG sub-module covering graph browsing, multi-hop retrieval and community-summary QA; skill packs inject with preview and per-session toggles; the companion ontology extracts knowledge candidates after each conversation and merges confirmed entries into the graph and retrieval sources — the agent grows to understand your domain.
• Open integration — every agent is itself an MCP server (the /mcp endpoint): any MCP client (Claude Desktop, Cursor, …) can connect and chat; execution backends are pluggable behind one interface: in-process assembly (default) / Docker sandbox (one container per agent) / Kubernetes Pod.

Ontology engineering: a full lifecycle from build to audit

• Multiple build paths, AI output must pass the quality gate — manual modeling, OntoChat guided authoring, CQ-driven evolution, build-from-knowledge-base, CSV import and more; LLM-generated content enters the library only after quality-gate scoring and self-repair.
• Paper-grade methods, internalized — OntoChat's four steps (CQ extraction → purification → analysis → testing) and OntoExtend's three-stage pipeline (retrieve → generate → integrate) are implemented per the papers and regression-tested; competency questions (CQs) graduate from one-off artifacts to re-runnable regression baselines — a session-level test station, dual-track quick screening + SPARQL fine judgement, and three-level coverage quantification on the term / property layers.
• Multi-form asset management — version snapshots & diff, source view, SPARQL workbench, 3D force-directed graph + WebVOWL semantic view, import/merge review wizard, publish state machine; lossy imports are reported honestly.
• Runtime plane — Oxigraph / Fuseki engine profiles (with an OWL reasoning switch), one-click engine install, a load-reconciliation hard gate (source/engine triple counts compared, mismatch aborts startup), and per-graph isolation for multi-ontology profiles.
• Consumption & audit — a KG retrieval observatory over TTL / text sources plus a full decision audit trail — the ontology is not just a modeling artifact but a consumable, accountable runtime asset.

Engineering & product form

• Single-machine deployable, all local — one command to start (run-dev.sh), no Python runtime dependency; data, keys, knowledge and ontologies never leave the machine.
• Desktop clients — Windows / macOS installers (Tauri 2 shell): system tray, single instance, whole-process-tree teardown, one-click install for engines and the sidecar on first launch.
• Platform knowledge shipped in-app — product design, technical principles, module guides and research notes render in place; capability boundaries are honestly labeled (e.g. KG-augmented retrieval is a lightweight implementation).
• Quality assets maintained in-repo — a regression smoke-test checklist plus headless UI smoke suites, so every delivery round is verifiable and replayable.

🚀 Quick Start

Run from source

Linux / macOS:

./run-dev.sh          # Windows: .\run-dev.ps1
# open http://localhost:8080

First launch automatically initializes the SQLite database (backend/data/platform.db) and creates a preset DeepSeek model connection.

Configure a model (required)

Open Settings → Model Management, edit DeepSeek (preset), fill in your API key and click Test Connection — or add any OpenAI-compatible / Anthropic-compatible connection (custom base_url + model). Keys are stored locally only, never uploaded.

Desktop installers

The shell starts the local services and opens the platform window:

• Windows — see deploy/windows/README.md
• macOS — see deploy/macos/README.md

For Docker Compose, Helm and environment variables, see the deployment guide.

💻 Development Mode (frontend hot reload)

cd backend && go run ./cmd/backend   # terminal 1 (:8080)
cd web && npm run dev               # terminal 2 (:5173, proxies API to :8080)

🧱 Tech Stack

🗂 Repository Layout

backend/             Go main platform backend (:8080, also hosts the web UI)
ontology-service/    Ontology build plane (:8091, multi-form assets / quality gate)
runtime-manager/     Ontology runtime plane (:8090, engine profile management)
web/                 React 18 + Vite + TS frontend
apps/desktop/        Desktop client (Tauri shell frontend, Windows / macOS)
pkg/                 Shared Go modules (SQLite migration runner / ontology spec / SPARQL guard)
hooks/               Git hooks (pre-commit doccheck gate; enable once: git config core.hooksPath hooks)
wrappers/            External agent integration wrappers (e.g. AgentScope A2A)
data/ logs/          Local runtime data & logs (gitignored, created on first run)
website/             Project website (GitHub Pages; auto-deploys on push to main)
docs/                Requirements & progress area (numbered source-of-truth docs, see index below)
docs/handbook/       Current-state manual — in-app "platform knowledge" page tree + assistant RAG
docs/research/       Process research archive (off the page & vector index)
docs/learning/       Learning assets — in-app "learning assets" group + RAG
seeds/learning/      Single source for skill packs & sample ontology content — end-user teaching content (distinct from docs/learning/, the platform's own knowledge assets)
deploy/              Docker Compose + Helm + desktop build scripts
tools/ research/ smoke/   Utilities, research notes, smoke-test suites

📚 Documentation

A directional overview follows in Roadmap; requirement status details live in docs/02 §12 and docs/18 — they are intentionally not duplicated here.

🧭 Roadmap

The project has grown from a teaching demo into a production-grade, single-machine deployable product: desktop installers on both platforms, a quality gate and regression smoke-test system in place. Positioning now anchors on a personal work & learning assistant grounded on ontologies (Q-23, 2026-10-28). Work continues along the two cores plus the assistant product surface; the directions below are an overview (authoritative requirement rows, priorities and delivery status live in docs/02 §12 and docs/18; some items are trigger-driven):

🙏 Appreciation

OntoAgents stands on the shoulders of the open-source community and academic work — direct dependencies are used under their own licenses; methodological borrowings follow the principle of borrowing ideas, implementing ourselves. The lists below are grouped by this project's architecture layers (direct use) and by domain (key references); the full ledger (with requirement links, evaluation notes and rejected candidates) lives in docs/15_开源项目及论文登记簿.md.

Directly used — by architecture layer

Agent engine (Go backend)

Ontology plane (build & runtime)

Frontend (React)

Desktop & delivery

Key references (ideas borrowed, implemented in-house)

Ontology methodology & toolchain（含引导使用 guided execution paths——平台外使用、产物回流）

Knowledge systems & retrieval

Product & learning-space references

Papers & standards

| OntoChat: a Framework for Conversational Ontology Engineering using Language Models (ESWC 2024) | arXiv 2403.05921 | The four-step conversational OE workflow (user story → CQ → clustering → testing) and practitioner survey |
| Improving Ontology Requirements Engineering with OntoChat and Participatory Prompting | arXiv 2408.15256 | The participatory prompting protocol (user-story guidance) |
| OntoChat Assistant for User Story Generation in Ontology Engineering | ACM DL 10.1145/3810943 | A design-validated prompting framework for user-story generation |
| OntoExtend: A Framework for Requirement-driven and Scalable Ontology Extension with LLMs | arXiv 2607.17963 | The requirement-driven three-stage pipeline, retrieval experiments and triple evaluation |
| Ontology extension by online clustering with LLM agents (Frontiers in Big Data 2024) | DOI 10.3389/fdata.2024.1463543 | Zero-shot streaming ontology extension route |
| CQ4OE: A Benchmark for Assessing LLM-assisted Ontology Generation | arXiv 2609.26029 | CQ-alignment benchmark: multi-dimensional metrics and three-level CQ coverage |
| MASEO: Multi-Agent System for Explainable Ontology Generation (LLMs4KG 2026) | PDF | Four-stage multi-agent generation pipeline (generate → syntax → consistency → pitfalls), a reference for build-pipeline orchestration |
| LLMs for Ontology Engineering: A Systematic Literature Review (Semantic Web Journal) | DOI 10.1177/22104968261465514 | Survey of the three LLM roles (engineer / expert / evaluator) |
| IDEA2: Expert-in-the-loop Competency Question Elicitation | arXiv 2604.01344 | Semi-automatic CQ elicitation workflow with provenance tracking |
| NeOn Methodology (Suárez-Figueroa et al., Springer 2012) | —— | Scenario-based ontology lifecycle methodology; one source of our seven-stage build model |
| Ontology Development 101 (Noy & McGuinness, 2001) | Stanford | The classic modeling primer; baseline textbook of the learning content pack |
| Gruninger & Fox: The Design and Evaluation of Ontologies (TOVE, 1995) | —— | Original source of the competency-question methodology |
| ReAct: Synergizing Reasoning and Acting in Language Models | arXiv 2210.03629 | The reasoning-acting interleaved paradigm (engineering paradigm behind the Eino ADK agent mode) |
| From Local to Global: A Graph RAG Approach to Query-Focused Summarization (Microsoft Research) | arXiv 2404.16130 | Theoretical source of GraphRAG: community summaries + query-focused summarization |
| LLM Wiki: a pattern for building personal knowledge bases using LLMs (A. Karpathy) | Gist | The "compile knowledge at write time, keep it fresh" pattern — a reference for the write-time accumulation route of the knowledge base and companion ontology |
| Model Context Protocol (MCP) specification | modelcontextprotocol.io | The integration protocol across the platform: tool consumption plus agent / ontology facade serving |
| RDF 1.1 / OWL 2 / SHACL / SPARQL 1.1 / PROV-O (W3C) | RDF · OWL 2 · SHACL · SPARQL 1.1 · PROV-O | Standards behind the data model, expressivity baseline, constraint validation, query language and provenance ontology |

❓ FAQ

No usable model connection is configured — add your API key in Settings → Model Management.

./run-dev.sh 9090 or .\run-dev.ps1 -Port 9090.

Stop the service and delete backend/data/ (this wipes all conversations and configuration).

An embedding connection is missing or the index is not ready; the knowledge page shows a status badge and onboarding. DeepSeek has no embedding API, so configure a separate vector service (e.g. SiliconFlow BGE, Qianfan embeddings-v1).

🤝 Contributing

Read CONTRIBUTING.md first — it defines two contribution channels: bug fixes / docs / small features go the light path (no REQ paperwork — requirement registration and doc write-back are handled by the maintainer on merge), larger features start with an issue first. Issues and PRs in Chinese or English are both welcome.

• Report bugs via the issue templates; issues labeled good first issue / help wanted are ready to pick up.
• Security vulnerabilities: follow SECURITY.md — private disclosure, no public issues.
• Everyone interacting with the project follows the Code of Conduct.
• Requirements and design documents in docs/ are the source of truth; regression checks follow docs/20_回归冒烟清单.md; AI coding assistants read AGENTS.md first.

📜 License

Apache-2.0