# AI use cases for Master Agent (OpenSparX/MasterAgent)

Repo: [OpenSparX/MasterAgent](https://github.com/OpenSparX/MasterAgent) | Use cases: 5 | Page: https://dedupedai.com/use-cases/opensparx-masteragent/

A C++17 local-first agent runtime and sparx CLI that matches deterministic phrases first, calls a model only when configured, and runs only validated tool calls.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Run the offline agent demo in under an hour: https://dedupedai.com/use-cases/opensparx-masteragent/try-offline-agent-runtime-demo/
- Add phrase-routed tools to a C++ app: https://dedupedai.com/use-cases/opensparx-masteragent/embed-runtime-in-cpp-app/
- Stop repeated tool runs after a crash: https://dedupedai.com/use-cases/opensparx-masteragent/avoid-duplicate-tool-runs-after-crash/
- Send unmatched commands to a local model: https://dedupedai.com/use-cases/opensparx-masteragent/route-commands-to-local-model-server/
- Study an idempotent inventory tool integration: https://dedupedai.com/use-cases/opensparx-masteragent/build-idempotent-business-tool-example/

## How to run the offline agent demo in under an hour with Master Agent

Repo: [OpenSparX/MasterAgent](https://github.com/OpenSparX/MasterAgent) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Build the sparx CLI and watch a simulated AC command route through deterministic skills.

**Who it is for:** A developer or evaluator who wants to see how a local agent runtime handles a command with no model, network or hardware.

**The problem:** Most agent demos need API keys, a cloud model or real devices before anything runs, which makes a quick evaluation slow.

**The outcome:** A built sparx binary and JSON output from a demo that sets and reads back a simulated AC temperature, plus a passing test run.

### Steps

1. Clone the repo with `git clone https://github.com/OpenSparX/MasterAgent.git` and enter the folder with `cd MasterAgent`.
2. Configure and build with `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release` and `cmake --build build --parallel 4`.
3. Run the tests with `ctest --test-dir build --output-on-failure`.
4. Run the demo with `./build/cli/sparx demo automotive`.
5. Try a phrase with `./build/cli/sparx run --input '把空调调到22度'` and an unmatched one to confirm NO_ROUTE.

### Prompt to paste into your agent

```text
Using the repo OpenSparX/MasterAgent, build it with CMake Release, run ctest, then run `./build/cli/sparx demo automotive`. Report the JSON output and whether all tests passed. Verify that the simulated AC state is read back from the same run.
```

### Caveat

The demo state is in memory and resets each process, and the README makes no latency or NPU performance claim for this build.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/opensparx-masteragent/try-offline-agent-runtime-demo/

## How to add phrase-routed tools to a C++ app with Master Agent

Repo: [OpenSparX/MasterAgent](https://github.com/OpenSparX/MasterAgent) | Difficulty: Advanced | Time: 1 hour | Basis: From the README

Link the installed SDK into your own C++ program and register host tools with exact-phrase skills.

**Who it is for:** A C++ engineer who has an existing application and needs a text or voice command layer that only calls approved functions.

**The problem:** Wiring free-form input straight to application functions is risky, so the app needs a runtime that checks tool names and arguments first.

**The outcome:** Your application links Master Agent::Core, registers a tool and phrase skills, and returns typed results from Runtime::run().

### Steps

1. Install the SDK with `cmake --install build --prefix "$PWD/install-sdk"` after the build step.
2. Read the public API in `include/master_agent/runtime/reference_runtime.h` and the rules in the integration contract at `docs/reference_runtime.md`.
3. Add `find_package(MasterAgent CONFIG REQUIRED)` and `target_link_libraries(your_app PRIVATE MasterAgent::Core)` to your CMakeLists.txt.
4. Register a tool with a supported parameter schema and callback, then register exact phrase skills.
5. Build the consumer with `cmake -S examples/reference_agent -B build-consumer -DCMAKE_PREFIX_PATH="$PWD/install-sdk"` and `cmake --build build-consumer` as a reference, then run `ctest --test-dir build-consumer --output-on-failure`. (inferred, check the README)

### Prompt to paste into your agent

```text
Using the repo OpenSparX/MasterAgent, add MasterAgent::Core to <your app target> in CMake, register one tool and one exact-phrase skill from reference_runtime.h, and call Runtime::run() on a test phrase. Expected output is a typed tool result, not free text. Verify that an unknown tool name is rejected.
```

### Caveat

The README says the schema support is a primitive object subset and the SDK is a small synchronous runtime, so plan your tool shapes around that.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/opensparx-masteragent/embed-runtime-in-cpp-app/

## How to stop repeated tool runs after a crash with Master Agent

Repo: [OpenSparX/MasterAgent](https://github.com/OpenSparX/MasterAgent) | Difficulty: Advanced | Time: 1 hour | Basis: From the README

Persist requests in SQLite so a repeated request returns the saved result instead of running again.

**Who it is for:** An operations engineer running an agent that changes a real system and must not apply the same change twice after a restart or failure.

**The problem:** If a process dies mid-request, it is unclear whether the tool ran, and retrying can repeat the change.

**The outcome:** Repeated requests return the recorded outcome, and interrupted requests are marked UNKNOWN for external checking and explicit reconciliation.

### Steps

1. Build with SQLite support by following the Quick start build steps with libsqlite3 development files installed.
2. Run a request with state and identity using `./build/cli/sparx run --state ./state/agent.db --session alice --request-id ac-001 --input 'set AC to 22 degrees'`. (inferred, check the README)
3. Repeat the same command after a restart and confirm it returns the recorded outcome without a second tool call.
4. After an interruption, run `./build/cli/sparx recover --state ./state/agent.db` to mark unfinished requests as UNKNOWN.
5. Check the external system for each UNKNOWN request, then follow the recovery guide at `docs/durable_recovery.md` to reconcile it.

### Prompt to paste into your agent

```text
Using the repo OpenSparX/MasterAgent, run `sparx run --state ./state/agent.db --session <session> --request-id <id> --input '<command>'` twice, restarting between runs, then run `sparx recover --state ./state/agent.db`. Expected output is the same recorded outcome on the second run and any unfinished requests listed as UNKNOWN. Verify that the tool was not invoked a second time.
```

### Caveat

The README states there is no transaction across a real device and SQLite, so this is not an exactly-once guarantee, and storage is not encrypted.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/opensparx-masteragent/avoid-duplicate-tool-runs-after-crash/

## How to send unmatched commands to a local model with Master Agent

Repo: [OpenSparX/MasterAgent](https://github.com/OpenSparX/MasterAgent) | Difficulty: Intermediate | Time: 1 hour | Basis: From the README

Point sparx at a llama-server you run yourself so unmatched phrases reach a local model.

**Who it is for:** A developer who already runs a local GGUF model and wants natural-language commands validated before any tool runs.

**The problem:** Model output can name tools that do not exist or pass bad arguments, so the model's answer needs strict checks before execution.

**The outcome:** Phrases that the skills do not match go to your model, and only valid tool calls run, with the real tool result returned.

### Steps

1. Start a compatible llama-server yourself with your chosen GGUF model, since the CLI does not download or start one.
2. Build the CLI with libcurl available, following the Quick start steps.
3. Run `./build/cli/sparx run --endpoint 127.0.0.1:8080 --model local --input 'Set the AC to 24 degrees'`. (inferred, check the README)
4. Set `--timeout-ms 3000` if the model is slow, and confirm malformed model output returns an error rather than a guessed call.
5. For an authenticated endpoint, export your key and pass only its variable name with `--api-key-env MODEL_API_KEY`.

### Prompt to paste into your agent

```text
Using the repo OpenSparX/MasterAgent, start a local llama-server with <your GGUF model>, then run `sparx run --endpoint 127.0.0.1:8080 --model local --input '<phrase>'`. Expected output is either a validated tool result or an error. Verify that a phrase asking for an unknown tool returns an error, not a tool call.
```

### Caveat

The README says model compliance depends on the model you choose, and it does not verify real-model latency or Qualcomm NPU performance for this release.

Risk, credentials: Keep the model API key in an environment variable and pass only its name to --api-key-env, never as a command-line argument.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/opensparx-masteragent/route-commands-to-local-model-server/

## How to study an idempotent inventory tool integration with Master Agent

Repo: [OpenSparX/MasterAgent](https://github.com/OpenSparX/MasterAgent) | Difficulty: Advanced | Time: 2 hours | Basis: From the README

Use the inventory example to see how a business tool commits once and recovers lost responses.

**Who it is for:** A backend engineer who must connect an agent to a service that changes stock or orders and needs safe retries.

**The problem:** A dropped response after a successful write can cause a second decrement when the agent retries.

**The outcome:** A working reference for context-aware tools that return committed, failed or unknown outcomes, with a passing integration test.

### Steps

1. Read the example guide at `examples/inventory_agent/README.md`.
2. Confirm the main build and tests pass with `ctest --test-dir build --output-on-failure`.
3. Read the execution contract in `docs/reference_runtime.md` for context, deadline and cancellation fields.
4. Run the inventory integration test described in the example guide and check that the lost-response case reconciles.
5. Adapt the tool's idempotency key scheme to your own service's receipt table.

### Prompt to paste into your agent

```text
Using the repo OpenSparX/MasterAgent, open examples/inventory_agent/README.md and run its integration test. Expected output is a passing test showing UNKNOWN recovery and no second stock decrement. Verify that the test covers a response dropped after commit.
```

### Caveat

The README describes this as a local business-service example, not a real-model or third-party production validation.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/opensparx-masteragent/build-idempotent-business-tool-example/