OAK Local Agent Runtime
Embed a C++ runtime that runs deterministic skills first and validates tool calls before execution.
- Source repo
- OpenSparX/MasterAgent
- Stars
- ★ 1k
- Last updated
- 1mo ago
- License
- Apache-2.0
- Primary language
- C++
- FA score
- 60/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Automotive software teams can prototype an in-car control flow with
sparx demo automotive, without a real vehicle or model. - Not a fit if
- Teams requiring verified Qualcomm QNN/Genie integration
- Projects needing production encryption or durable multi-step DAGs
- Source review
- 60/100 · Some gaps
What does this agent do, and when should you use it?
OAK / MasterAgent is a local-first C++17 runtime released as a working sparx CLI and an installable C++ SDK. Its master_agent::reference API lets an application register tools, parameter schemas, callbacks, and exact-phrase skills; deterministic skills run before any optional model request. The runtime validates tool names and arguments, then returns the actual tool result; unmatched input returns NO_ROUTE when no model is configured. Session state is in memory by default, while explicit SQLite storage persists execution receipts and history for request deduplication and interrupted-request recovery across restarts. The reference runtime does not include Qualcomm QNN/Genie integration, so that platform connection requires separate work.
Run sparx demo automotive to set and read back an in-memory simulated AC temperature, with JSON output. sparx run --input ... handles a single input; interactive line input can retain demo state within one process. The runtime checks registered exact-phrase skills first, then can invoke a model callback or the local-model HTTP adapter; a model may return JSON or one tool call, and the tool name and arguments must pass validation before execution. SQLite receipts and history can be enabled with --state, --session, and --request-id; repeated requests return their recorded outcome, while unfinished requests become UNKNOWN for verification and explicit reconciliation. SDK context-aware tools also receive request identity, a stable idempotency key, a deadline, and a cooperative cancellation signal.
- Automotive software teams can prototype an in-car control flow with
sparx demo automotive, without a real vehicle or model. - Embedded C++ developers can link
MasterAgent::Coreinto an application and register business tools constrained by parameter schemas. - Teams that want local inference can connect a separately launched llama-server through the HTTP adapter.
- Business applications needing request deduplication across process restarts can opt into SQLite receipts and history.
- Inventory service developers can study the inventory example's separate HTTP service and its lost-response UNKNOWN recovery and reconciliation flow.
How do you install or deploy this agent?
Requires CMake 3.18+ and C++17. The optional HTTP adapter needs libcurl development files; durable storage needs SQLite development files. Tests and packaging require Python 3. Release CI targets Linux and macOS.
git clone https://github.com/OpenSparX/MasterAgent.git
cd MasterAgent
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 4
ctest --test-dir build --output-on-failureOn Ubuntu, the README lists these HTTP and SQLite development packages:
sudo apt-get install libcurl4-openssl-dev libsqlite3-devBuild the SDK and deterministic CLI without libcurl:
cmake -S . -B build-offline -DMASTER_AGENT_ENABLE_HTTP=OFF -DBUILD_EVAL=OFF
cmake --build build-offline --parallel 4To omit both optional dependencies:
cmake -S . -B build-minimal -DMASTER_AGENT_ENABLE_HTTP=OFF -DMASTER_AGENT_ENABLE_STORAGE=OFF
cmake --build build-minimal --parallel 4How do you use this agent?
Start with the in-memory simulated demo; it needs no model, credentials, network, or vehicle hardware:
./build/cli/sparx demo automotiveTry inputs against registered skills:
./build/cli/sparx run --input '把空调调到22度'
./build/cli/sparx run --input 'vehicle status'Connect to a compatible llama-server that you start separately. The runtime does not download or start a model and has no automatic cloud fallback:
./build/cli/sparx run --endpoint 127.0.0.1:8080 --model local \
--input 'Set the AC to 24 degrees'Set a timeout and authentication by putting the key in an environment variable and passing its name:
./build/cli/sparx run --endpoint 127.0.0.1:8080 --model local \
--timeout-ms 3000 --api-key-env MODEL_API_KEY \
--input 'Set the AC to 24 degrees'Opt into SQLite persistence and inspect recovery after a restart:
./build/cli/sparx run --state ./state/agent.db --session alice --request-id ac-001 \
--input 'set AC to 22 degrees'
./build/cli/sparx recover --state ./state/agent.dbFor SDK integration, install the package and use CMake find_package(MasterAgent CONFIG REQUIRED), then link MasterAgent::Core; MasterAgent::Http is optional. The supported public entry point is reference_runtime.h under master_agent::reference.
What are this agent's strengths and limitations?
- Deterministic exact-phrase skills run without a model, and the automotive demo needs no network or vehicle hardware.
- The
master_agent::referenceAPI provides an installable C++ SDK, tool registration, and argument validation. - Optional SQLite receipts support request deduplication after restarts and mark unfinished requests
UNKNOWNfor verification. - Context-aware tools receive a stable idempotency key, deadline, and cooperative cancellation signal, and return explicit committed, failed, or unknown outcomes.
- The release is version 0.4.0-alpha.3; the README describes it as a small synchronous reference runtime.
- The HTTP model adapter requires a separately running compatible llama-server, and model compliance depends on the selected model.
- Tool schemas support only a primitive object subset; SQLite is unencrypted and cannot share a transaction with a real device or guarantee distributed exactly-once execution.
- Qualcomm QNN/Genie integration requires platform work and is not verified; experimental modules are not wired into the reference CLI.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| OAK Local Agent Runtime This agent | 60 · Some gaps | CLIFree | ★ 1k | 1mo ago | C++ | — |
| Dexto | 51 · Major gaps | CLIFree + model costs | ★ 660 | 1d ago | — | Claude Code · OpenAI API · Claude API |
| Coven | 79 · Good | CLIFree | ★ 76 | today | Rust | Codex · Claude Code |
| Aura IDE | 77 · Good | Desktop appFree + model costs | ★ 57 | 1mo ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The README shows tool-name and argument validation, opt-in persistence, API keys supplied through an environment-variable name, and recovery and reconciliation paths. This supports moderate least-privilege, data-flow transparency, and external-effect controls. A general user-confirmation flow is not shown, storage is unencrypted, and dependency-security evidence is limited. The README and test source describe UNKNOWN recovery with audit records, but do not establish a general rollback guarantee. The license and SECURITY.md provide contact information, but publisher identity is unverified and maintenance ownership and update paths remain thin.
The README describes a synchronous reference runtime and error handling, while test source covers crash recovery and evaluation failures. However, SECURITY.md calls 0.3.x current while the README labels the release 0.4.0-alpha.3. Optional dependencies and installation requirements are documented, and states such as NO_ROUTE, UNKNOWN, and STORAGE_ERROR are named. These tests were not executed for this assessment.
The README addresses C++ SDK integrators and CLI users, with deterministic skills, host tool callbacks, a model adapter, and persistence scenarios. It clearly says Qualcomm QNN/Genie is unverified, experimental modules are not wired into the reference CLI, there is no automatic cloud fallback, and multi-step durable DAGs are not supplied. Exact-phrase skill routing constrains triggers, while natural-language coverage and real-device adaptation remain limited.
The README organizes quick start, model use, persistence, SDK integration, capability status, and limitations, with build, install, and example instructions; the Apache-2.0 license file is present. The release is labeled alpha, but the supplied files show no changelog, and SECURITY.md version information conflicts with the README. The vulnerability-reporting email and response commitments offer limited maintenance guidance, but publisher identity and full maintenance responsibility are not established.
JSON output, a CLI, an SDK, deterministic skills, and a recovery-oriented business example provide practical value for local tool execution and integration. The README explains dependency, model-service, and storage choices and discloses limitations. The description's sub-100ms Qualcomm NPU and fully on-device claims are not supported by the supplied evidence; QNN integration is explicitly unverified.
The README's setup, capability, and limitation statements can be partially compared with the CI workflow and test source. The crash-recovery test source contains concrete state, reconciliation, and audit assertions, but cross-source corroboration is limited and the tests were not run for this review. The documentation distinguishes shipped features, experimental modules, simulated evaluations, and unverified performance or hardware claims, keeping fact and inference reasonably separate.
- Treat the sub-100ms Qualcomm NPU and fully on-device description as unverified: the README says QNN/Genie integration is unverified, and synthetic evaluations do not establish real-model latency or NPU performance.
- Version signals conflict: the README labels 0.4.0-alpha.3, while SECURITY.md lists 0.3.x as current; persisted data is unencrypted.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Full Changelog: https://github.com/OpenSparX/MasterAgent/compare/v2.1.14...v2.1.15View on GitHub ↗ -
Release notes excerpt
Full Changelog: https://github.com/OpenSparX/MasterAgent/compare/v2.1.13...v2.1.14View on GitHub ↗ -
Release notes excerpt
Full Changelog: https://github.com/OpenSparX/MasterAgent/compare/v2.1.5...v2.1.6View on GitHub ↗
FAQ
Do I need a model or a paid API key?
--api-key-env.Will input be sent to the cloud automatically?
Does SQLite guarantee a device operation runs exactly once?
UNKNOWN and need external verification and explicit reconciliation.