MasterAgent

原生端侧智能体内核 — Native by design, open by nature.

Build AI agents that run 100% on-device. 构建 100% 本地运行的 AI Agent。

No cloud APIs. No latency. No privacy leaks. 无需云端 API · 无网络延迟 · 无隐私泄露

是什么

OAK 是面向终端设备的开源智能体操作系统内核，为 AI Agent 提供端侧推理、任务调度、工具调用与硬件加速的完整软件基座。

OAK 之于 Agent OS，如同 Linux 内核之于安卓 / Ubuntu。我们不做完整操作系统，我们提供开源开放的内核层，车企、手机厂商、机器人公司基于 OAK 自研专属 Agent OS。

English · 中文

🚀 Why On-Device Agents?

Cloud-based agents are slow, expensive, and leak your data. Every request goes to a remote API — adding 2–5s of latency, costing $0.01–0.05 per call, and sending your prompts to third-party servers.

Sparx runs the entire agent pipeline locally:

🎬 See It in Action

Automotive voice assistant — turn natural language into vehicle control:

sparx demo automotive

# 🚗 Automotive Voice Assistant
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
# You: "Turn on AC, set to 22°C, interior mode"
#
# ⚙️  Processing...
# ├─ Intent: climate_control ✓
# ├─ Skills: ac.power, ac.temperature, ac.circulation ✓
# ├─ MCP Services: vehicle.climate [87ms] ✓
# └─ Result: Climate control updated ✓
#
# ⚡ Latency: 87ms

Execution plan builder — visualize multi-step agent workflows:

sparx plan show examples/automotive_assistant/plans/turn-off-ac.yaml

# Plan: turn-off-ac (priority=p1, deadline=3000ms)
#
# ┌─────────────┐
# │  read_temp  │  vehicle.climate.getTemperature
# └──────┬──────┘
#        ▼
# ┌─────────────┐
# │   set_ac    │  vehicle.climate.setPower (power: off)
# └─────────────┘
#
# ✓ valid — 2 nodes, 1 dependency

🏗️ Architecture

Every request flows through a deterministic-first pipeline — most requests never touch an LLM:

1. Input — Voice / text from the user
2. Preprocessing & Memory — UTF-8 normalization, parameter extraction, conversation history
3. Deterministic Skills (80% of cases) — Pattern matching & rule-based routing at sub-millisecond latency, no model call
4. Intent Recognition (20% of cases) — LLM inference on CPU or NPU, only for ambiguous or complex requests
5. Task Orchestrator — Multi-step DAG execution with MCP service coordination
6. WAL Recovery — Write-Ahead Logging with UNKNOWN terminal state for crash safety
7. Response — Action results, typically sub-100ms end-to-end

Key components:

• Preprocessing: Input validation, UTF-8 normalization, parameter extraction
• Memory: Short-term context (conversation history, user preferences)
• Skills: Deterministic pattern matching — 80% of requests route here
• Qualcomm NPU: Optional hardware acceleration (10–100x faster than CPU)
• MCP Services: Modular capabilities (vehicle control, navigation, smart home, etc.)
• WAL Recovery: Write-Ahead Logging with UNKNOWN terminal state

💎 What Makes Sparx Different?

1. Unknown Terminal State — Industry First

The problem: What happens when your agent crashes mid-payment?

sparx demo crash

# Simulates power loss during payment:
#
#   ⚠️  payment.charge → side_effect=UNKNOWN
#   idempotency_key: a3f1c7e2
#   amount: 49.99 CNY
#
#   → Requires manual reconciliation (sparx reconcile)
#
#   Why this matters:
#   - Retrying may duplicate the charge
#   - Ignoring may lose the money
#   - UNKNOWN is the only honest answer

Read more: WAL Recovery Mechanism

2. Deterministic-First Routing

80% of requests never touch the model. Sparx uses pattern matching and rule-based skills for common tasks — saving latency and compute:

# skills/climate.yaml
name: climate_control
trigger:
  patterns:
    - "turn {power} (the )?AC"
    - "set temperature to {temp}"
handler:
  type: deterministic
  action: vehicle.climate.setPower

Only ambiguous or complex requests invoke the LLM. Most requests route in microseconds.

3. Optional NPU Acceleration

Develop on any machine (Mac/Linux/Windows) using CPU inference. Deploy to Qualcomm NPU devices for 10–100x speedup:

Supported NPU platforms: SA8155P, SA8295P, SA8650P, SA8775P (automotive); Snapdragon 8 Gen 3+ (mobile, coming Q4 2026)

⚡ Quick Start

Install

Option 1: npm (recommended)

npm install -g @sparx/cli

Option 2: Homebrew (macOS)

brew install OpenSparX/masteragent/sparx

Option 3: curl (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/OpenSparX/MasterAgent/main/scripts/install.sh | sh

Create Your First Agent

# 1. Initialize a new project
sparx init my-agent
cd my-agent

# Generated structure:
# my-agent/
# ├── agent.yaml          # Agent configuration
# ├── skills/
# │   └── hello.yaml      # Skill definitions
# └── .sparx/
#     └── wal.log         # Recovery log

# 2. Download a model (~530 MB, takes 1–2 min)
sparx pull qwen2.5-0.5b-instruct

# 3. Run locally (CPU inference, no GPU/NPU needed)
sparx run --model ~/.sparx/models/qwen2.5-0.5b-instruct-q8_0.gguf

# Agent "my-agent" is running. Type a message or Ctrl+C to exit.
# > hello
# ✓ route=deterministic  skill=hello  0.02ms   (model not invoked)
# > what is the capital of France?
# ✓ route=inference  ttft=142ms  total=1830ms  tokens=28
#   The capital of France is Paris.

# 4. Try built-in demos
sparx demo automotive     # Voice assistant
sparx demo crash          # WAL recovery simulation

💡 Tip: sparx run without --model still works — deterministic skills (pattern-matched responses) answer normally. Only open-ended questions require a model. Add model.path in agent.yaml to avoid typing the path every time.

Build Execution Plans

# Create a YAML plan spec
cat > plans/my-plan.yaml <<EOF
plan: my-task
priority: p1
deadline_ms: 3000

nodes:
  - id: fetch_data
    action: api.getData

  - id: process
    action: logic.transform
    after: [fetch_data]
EOF

# Validate against the orchestrator
sparx plan validate plans/my-plan.yaml

# Visualize as Mermaid diagram
sparx plan export plans/my-plan.yaml --format=mermaid

# Export as JSON for programmatic use
sparx plan export plans/my-plan.yaml --format=json

📦 Examples

🚗 Automotive Voice Assistant

git clone https://github.com/OpenSparX/MasterAgent.git
cd MasterAgent/v2/examples/automotive_assistant
sparx run

# Supported commands:
# • "Turn on AC, set to 22°C"
# • "Navigate to nearest charging station"
# • "Play my favorite playlist"
# • "Call John"

🏠 Smart Home Control

cd examples/smart_home
sparx run

# Controls lights, temperature, security via MCP services

📡 IoT Edge Agent

cd examples/iot_edge
sparx run --low-power

# Optimized for battery-powered devices

🔌 Deploy to NPU Devices

Once you've developed your agent using CPU inference, deploy to Qualcomm NPU hardware for production:

# List connected devices
sparx devices

# Deploy to device
sparx deploy --device 1

# Interactive session
sparx shell

Supported platforms:

🗺️ Roadmap

• Core agent framework (v2.0)
• Qualcomm QNN NPU integration
• MCP service orchestration
• WAL recovery + Unknown terminal state
• CLI tool (init/run/deploy/doctor/plan)
• Multi-modal input (camera, LiDAR, radar) — Q3 2026
• Distributed agent orchestration — Q4 2026
• Edge-cloud hybrid mode — 2027
• More platforms (NVIDIA Jetson, Rockchip) — 2027

📚 Documentation

• System Overview — Architecture deep-dive
• Build and Test — Compilation guide
• WAL Recovery — Crash recovery mechanism
• MCP Services — How to add custom capabilities
• Qualcomm NPU — QNN SDK integration guide

❓ FAQ

No. Sparx runs on any Mac/Linux/Windows machine using CPU inference (llama.cpp). Qualcomm NPU is optional for production deployments where you need <100ms latency.