Model or dataset
OpenSparX/MasterAgent avatar
OpenSparX/MasterAgent

MasterAgent promises sub-100ms on a Qualcomm NPU, then declines to verify it

Build AI agents that run 100% on-device. Sub-100ms latency on Qualcomm NPU. Zero cloud dependency.

976 stars37 forksC++Apache-2.0

At a glance

What is it?
OAK / MasterAgent is a small C++17 runtime that matches exact-phrase skills before it calls a model, with optional SQLite receipts for request replay and an UNKNOWN state for interrupted tools. Its own capability table is the most useful page in the repository.
Who is it for?
MasterAgent is a good fit for an embedded agent that has to keep working when the network is gone, because the deterministic path, the argument validation and the committed, failed, unknown outcome triple are all spelled out at the API level. Two things to check before you commit.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 48 days ago.
What is it written in?
Mainly C++, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • OpenSparX/MasterAgent976 ★ · +603
Star history
Repository2026-09-132026-11-15
OpenSparX/MasterAgent373976

603 Stars in the last 63 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The NPU number on the front page is unverified in the capability table

The project description promises agents that run 100% on-device with sub-100ms latency on a Qualcomm NPU and zero cloud dependency. The capability table lower down says something narrower and more honest. Its row for Qualcomm QNN/Genie integration reads: platform integration required, not verified by this release. No measurement appears anywhere in the document to support the millisecond figure, and the row for the edge and cloud harness marks it experimental, explicit opt-in, with bounded outstanding inference workers. What the text does commit to is the absence of a fallback: a full HTTP(S) endpoint URL may be provided explicitly, and no cloud fallback happens automatically. The local-first claim is therefore structural, a property of the request path, while the NPU latency claim is a target that the same document declines to confirm for the code being published.

Two version lines: v2.1.x tags against a 0.4.0-alpha.3 README

The releases are v2.1.15 on 2026-08-12, v2.1.14 on 2026-08-12, and v2.1.6 on 2026-08-10, three tags inside three days. The README header describes something else entirely: 0.4.0-alpha.3, an open reference runtime with contextual tools and durable receipts, and it notes that public source now builds a working sparx CLI and an installable C++ SDK. Nothing in the document reconciles the two numbering schemes, and the repository carries a VERSION.json at its root alongside CHANGELOG.md and ARCHITECTURE.md, so a third place records a version. The tags also cluster rather than march: two landed on the same morning three days apart, and none of them carries the alpha marker the README puts on its own version. The last push on main is 2026-09-28, six weeks after the newest tag. Anyone installing by tag and anyone reading the README are looking at two different claims about what 0.4.0-alpha.3 or v2.1.15 contains.

The public source is not the kernel its own headers describe

One sentence settles what you are looking at: this is a small synchronous runtime, not the proprietary durable kernel described by the legacy interfaces. The capability table repeats the limit in its own row, marking multi-step durable DAG and legacy kernel factories as not supplied by this reference runtime. And it warns about the headers directly: other headers under include/master_agent/ describe legacy kernel contracts, and including them does not mean their factories have public implementations. The supported entry point is master_agent::reference. The tree explains why the distinction matters, carrying core/, backends/, templates/, android/, eval/, eval_mesh and eval_speculation next to cli/, include/ and tests/, so a reader who greps for a mesh or speculation interface will find directories whose relationship to the shipped CLI is described only in a capability row. Those rows are explicit that speculation, mesh, verification, learning and decoding are experimental modules with synthetic evaluations, not wired into the reference CLI, and that production encryption and DP learning guarantees are not claimed for this release.

Every sparx run starts a new demo state

The demo needs no model, no credentials, no network and no vehicle hardware. It sets an in-memory simulated AC temperature, reads it back, and prints JSON per line:

bash
./build/cli/sparx run --input '把空调调到22度'
./build/cli/sparx run --input 'vehicle status'

The first input is Chinese and the second is English, which shows the phrase matching is not English-only, and an unmatched phrase returns NO_ROUTE unless a model is explicitly configured. The catch is in the next paragraph: each process starts a new demo state, so those two lines share nothing. To keep state between requests inside one process you run sparx run and enter one input per line until EOF. That means a caller driving the binary from a shell script gets a fresh simulator on every invocation, and the persistence story has to come from the storage path instead of from the demo.

The model path asks for one tool call and refuses anything else

A local llama-server is started separately with your own GGUF model, and the runtime talks to it non-streaming on /v1/chat/completions:

bash
./build/cli/sparx run --endpoint 127.0.0.1:8080 --model local \
  --input 'Set the AC to 24 degrees'

The contract is narrow on purpose. The runtime asks for a JSON response or a single tool call, rejects unknown tools and invalid arguments, and returns the actual tool result rather than a description of it. Malformed output produces an error, never a guessed tool call, and model compliance depends on the model, so the failure mode is a refusal rather than a wrong action. Nothing is downloaded or started by the CLI. Credentials stay out of the argument list too: --api-key-env takes the name of an environment variable, so MODEL_API_KEY names the variable rather than carrying the secret, and --timeout-ms 3000 bounds the wait.

Durable storage records receipts, not device transactions

Persistence is opt-in and per request:

bash
./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.db

Repeating the same request after a restart returns the recorded outcome without calling the tool again, which is the deduplication guarantee. Anything interrupted becomes UNKNOWN, needs external verification, and is reconciled explicitly, and a database failure blocks further execution instead of silently switching back to memory. The limits are stated without hedging: only execution receipts and history are persisted, the AC simulator itself still resets on process restart, there is no transaction spanning a real device and SQLite so this is not a distributed exactly-once guarantee, and storage is not encrypted. Both optional dependencies can be dropped with MASTER_AGENT_ENABLE_HTTP=OFF and MASTER_AGENT_ENABLE_STORAGE=OFF, which is how the SDK is built without libcurl at all.

The consumer links one target and inherits the CMake package

The SDK is installed to a prefix and consumed through a config package:

cmake
find_package(MasterAgent CONFIG REQUIRED)
target_link_libraries(your_app PRIVATE MasterAgent::Core)
# Optional HTTP adapter:
# target_link_libraries(your_app PRIVATE MasterAgent::Http)

So the base install is one target and the HTTP adapter is opt-in at link time. The public API lives in reference_runtime.h: register a tool with a supported parameter schema and callback, register exact-phrase skills, optionally set a model callback, then call Runtime::run(). The older registerTool() API remains available next to the context-aware form, and context-aware tools receive the session and request identity, a stable scoped idempotency key, a deadline and a cooperative cancellation signal, then return an explicit committed, failed or unknown outcome. The capability table qualifies the schema support as a primitive object schema subset, so parameter validation is real but bounded.

The lost-response test proves one property and says so

The inventory example is the sharpest evidence in the repository, and the text is careful about what it proves. examples/inventory_agent talks to a separate HTTP service that commits inventory and an idempotency receipt in its own SQLite database. Its integration test deliberately drops a response after the commit, checks UNKNOWN recovery, reconciles against the service receipt, and shows there is no second stock decrement after either process restarts. Then the sentence that keeps it honest: this is a local business-service integration example, not a real-model or third-party production validation. The build side has its own limits. CMake 3.18 or newer, C++17, libcurl development files for the optional adapter and SQLite development files for durable storage, with Python 3 for tests and packaging, and the release CI targets Linux and macOS only, even though the tree carries an android/ directory.

Editorial conclusion

MasterAgent is a good fit for an embedded agent that has to keep working when the network is gone, because the deterministic path, the argument validation and the committed, failed, unknown outcome triple are all spelled out at the API level. Two things to check before you commit. The sub-100ms NPU number in the project description has no benchmark behind it and the capability table marks Qualcomm QNN/Genie integration as unverified for this release, and the two version lines do not match, since the GitHub tags are v2.1.x while the README labels the open source 0.4.0-alpha.3. Storage is not encrypted, so the SQLite state file holds receipts for anyone who can read it.

Frequently asked questions

Does OpenSparX/MasterAgent need a model for every request?

No. Deterministic exact-phrase skills are available with no model required, and the demo sets an in-memory simulated AC temperature and reads it back with no model, credentials, network or vehicle hardware. An unmatched phrase returns NO_ROUTE unless a model is explicitly configured.

What does MasterAgent persist when SQLite storage is enabled?

Only execution receipts and history. Repeating the same request after a restart returns the recorded outcome without calling the tool again, and a database failure blocks further execution instead of silently switching to memory. Storage is not encrypted.

Is the Qualcomm NPU path verified in the MasterAgent reference release?

Not by that release. The capability table lists Qualcomm QNN/Genie integration as requiring platform integration and not verified by this release, while the project description claims sub-100ms latency on Qualcomm NPU.

How does the MasterAgent CLI reach a local model?

With a non-streaming request to /v1/chat/completions on the endpoint passed to --endpoint, naming the model with --model. The runtime asks for a JSON response or a single tool call, rejects unknown tools and invalid arguments, and no model is downloaded or started by the CLI.

Which platforms does the MasterAgent release CI target?

Linux and macOS. The build needs CMake 3.18 or newer, C++17, libcurl development files for the optional HTTP adapter and SQLite development files for durable storage, and Python 3 for tests and packaging.

Official sources

  1. License: Apache-2.0
  2. OpenSparX/MasterAgent on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/opensparx-masteragent.svg)](https://hysenlabs.com/projects/opensparx-masteragent)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/opensparx-masteragent.svg)](https://hysenlabs.com/projects/opensparx-masteragent)

Was this useful?