⚡ Sparx

🌳 橡树 OAK · Open Agent Kernel

原生端侧智能体内核 — 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:

⚡ Sub-100ms Response	🔒 Private by Default	💰 Zero API Costs
No network round-trip	Data never leaves your device	Unlimited usage, $0/call

🚀 Works Offline	🎯 NPU-Accelerated
No internet dependency	Optional Qualcomm hardware, 10–100x speedup

🎬 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:

Input — Voice / text from the user
Preprocessing & Memory — UTF-8 normalization, parameter extraction, conversation history
Deterministic Skills (80% of cases) — Pattern matching & rule-based routing at sub-millisecond latency, no model call
Intent Recognition (20% of cases) — LLM inference on CPU or NPU, only for ambiguous or complex requests
Task Orchestrator — Multi-step DAG execution with MCP service coordination
WAL Recovery — Write-Ahead Logging with UNKNOWN terminal state for crash safety
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?

Framework	Behavior	Result
LangChain	Retries blindly	May charge twice 💸💸
AutoGPT	Ignores the error	Money lost silently 💸❓
Sparx	Enters `UNKNOWN` state	Requires explicit reconciliation ✅

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:

Platform	Backend	Latency	Power
Development (CPU)	llama.cpp	~1,200ms	8.1W
Production (NPU)	Qualcomm QNN	87ms	2.3W
Cloud (API)	OpenAI	2,500ms+	N/A

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. Add a custom skill
sparx add skill weather

# 3. Run locally (uses CPU inference by default)
sparx run

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

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:

Platform	SoC	Status	Notes
Automotive	SA8155P	✅ Supported	Gen 3
Automotive	SA8295P	✅ Supported	Gen 4
Automotive	SA8650P	✅ Supported	Gen 4+
Automotive	SA8775P	🔄 Testing	Gen 4
Mobile	Snapdragon 8 Gen 3	🔄 Planned	Q4 2026
IoT	QCS6490	🔄 Planned	2027

🗺️ 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

Do I need Qualcomm hardware to use Sparx?

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.

What models are supported?

Any GGUF model compatible with llama.cpp (Qwen2-4B, Qwen3-4B, Llama, Mistral, etc.). For NPU deployment, models need to be converted to QNN format.

Is this production-ready?

Yes. The v2.0 core has been tested in automotive scenarios with 15 test suites covering crash recovery, concurrency, and fault injection. Currently deployed in SA8295P-based vehicles.

How does WAL recovery work?

Sparx logs every side-effecting operation (API calls, payments, device control) before execution. If the agent crashes mid-operation, it resumes with three possible states: COMMITTED (success), FAILED (error), or UNKNOWN (crashed before status known). UNKNOWN requires manual reconciliation to prevent silent failures.

Can I use this for non-automotive applications?

Absolutely. While the showcase demo is automotive, Sparx works for any on-device agent use case: smart home, IoT, robotics, medical devices, industrial automation, etc.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Good first issues: https://github.com/OpenSparX/MasterAgent/labels/good%20first%20issue

💬 Community

📄 License

Apache 2.0 — see LICENSE

⚡ Sparx

构建 100% 本地运行的 AI Agent。

无需云端 API · 无延迟 · 无隐私泄露

# 60 秒安装运行 — 无需特殊硬件
npm install -g @sparx/cli && sparx demo automotive

🚀 为什么选择端侧 Agent？

云端 Agent 慢、贵、还泄露数据。每次请求都要发到远程 API — 增加 2-5 秒延迟，每次调用花费 $0.01-0.05，并将你的提示词发送到第三方服务器。

Sparx 将整个 Agent 流程搬到本地：

⚡ 亚百毫秒响应	🔒 默认隐私保护	💰 零 API 成本
无网络往返	数据不离开设备	无限使用，每次 $0

🚀 离线可用	🎯 NPU 加速
无需联网	可选 Qualcomm 硬件，10-100 倍提速

🎬 实际演示

车载语音助手 — 将自然语言转换为车辆控制：

sparx demo automotive

# 🚗 车载语音助手
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
# 你："打开空调，设置 22 度，内循环模式"
#
# ⚙️  处理中...
# ├─ 意图: climate_control ✓
# ├─ 技能: ac.power, ac.temperature, ac.circulation ✓
# ├─ MCP 服务: vehicle.climate [87ms] ✓
# └─ 结果: 气候控制已更新 ✓
#
# ⚡ 延迟: 87ms

执行计划构建器 — 可视化多步骤 Agent 工作流：

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

# 计划: turn-off-ac (优先级=p1, 超时=3000ms)
#
# ┌─────────────┐
# │  read_temp  │  vehicle.climate.getTemperature
# └──────┬──────┘
#        ▼
# ┌─────────────┐
# │   set_ac    │  vehicle.climate.setPower (power: off)
# └─────────────┘
#
# ✓ 有效 — 2 个节点, 1 个依赖

🏗️ 架构

每个请求都流经 确定性优先管线 — 大多数请求根本不触碰 LLM：

输入 — 用户的语音 / 文本
预处理 & 记忆 — UTF-8 规范化、参数提取、对话历史
确定性技能（80% 的情况） — 模式匹配与规则路由，亚毫秒延迟，不调用模型
意图识别（20% 的情况） — 仅在请求模糊或复杂时进行 LLM 推理（CPU 或 NPU）
任务编排器 — 多步骤 DAG 执行，协调 MCP 服务
WAL 恢复 — Write-Ahead Logging，带 UNKNOWN 终态的崩溃安全机制
响应 — 返回执行结果，端到端通常 低于 100ms

核心组件：

预处理： 输入验证、UTF-8 规范化、参数提取
记忆： 短期上下文（对话历史、用户偏好）
技能： 确定性模式匹配 — 80% 的请求在此路由
Qualcomm NPU： 可选硬件加速（比 CPU 快 10-100 倍）
MCP 服务： 模块化能力（车控、导航、智能家居等）
WAL 恢复： Write-Ahead Logging，带 UNKNOWN 终态

💎 Sparx 的独特之处

1. Unknown 终态 — 业界首创

问题： Agent 在支付过程中崩溃怎么办？

框架	行为	结果
LangChain	盲目重试	可能重复扣费 💸💸
AutoGPT	忽略错误	钱静默丢失 💸❓
Sparx	进入 `UNKNOWN` 状态	要求显式对账 ✅

sparx demo crash

# 模拟支付过程中断电：
#
#   ⚠️  payment.charge → side_effect=UNKNOWN
#   幂等键: a3f1c7e2
#   金额: 49.99 CNY
#
#   → 需要手动对账（sparx reconcile）
#
#   为什么重要：
#   - 重试可能导致重复扣费
#   - 忽略可能导致钱丢失
#   - UNKNOWN 是唯一诚实的答案

详细文档： WAL 恢复机制

2. 确定性优先路由

80% 的请求不触碰模型。 Sparx 使用模式匹配和基于规则的技能处理常见任务 — 节省延迟和算力：

# skills/climate.yaml
name: climate_control
trigger:
  patterns:
    - "把空调{power}"
    - "温度设为{temp}度"
handler:
  type: deterministic
  action: vehicle.climate.setPower

只有模糊或复杂的请求才调用 LLM。大多数请求在微秒级完成路由。

3. 可选 NPU 加速

在任何机器（Mac/Linux/Windows）上使用 CPU 推理开发。部署到 Qualcomm NPU 设备时获得 10-100 倍提速：

平台	后端	延迟	功耗
开发环境 (CPU)	llama.cpp	~1,200ms	8.1W
生产环境 (NPU)	Qualcomm QNN	87ms	2.3W
云端 (API)	OpenAI	2,500ms+	N/A

支持的 NPU 平台： SA8155P, SA8295P, SA8650P, SA8775P (车载); Snapdragon 8 Gen 3+ (手机，2026 Q4)

⚡ 快速开始

安装

方式 1：npm（推荐）

npm install -g @sparx/cli

方式 2：Homebrew（macOS）

brew install OpenSparX/masteragent/sparx

方式 3：curl（macOS / Linux）

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

创建第一个 Agent

# 1. 初始化新项目
sparx init my-agent
cd my-agent

# 生成的项目结构：
# my-agent/
# ├── agent.yaml          # Agent 配置
# ├── skills/
# │   └── hello.yaml      # 技能定义
# └── .sparx/
#     └── wal.log         # 恢复日志

# 2. 添加自定义技能
sparx add skill weather

# 3. 本地运行（默认使用 CPU 推理）
sparx run

# 4. 尝试内置演示
sparx demo automotive     # 语音助手
sparx demo crash          # WAL 恢复模拟

构建执行计划

# 创建 YAML 计划规范
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

# 针对编排器验证
sparx plan validate plans/my-plan.yaml

# 可视化为 Mermaid 图
sparx plan export plans/my-plan.yaml --format=mermaid

# 导出为 JSON 供程序化使用
sparx plan export plans/my-plan.yaml --format=json

📦 示例项目

🚗 车载语音助手

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

# 支持的命令：
# • "打开空调，设置 22 度"
# • "导航到最近的充电站"
# • "播放我最喜欢的歌单"
# • "给张三打电话"

🏠 智能家居控制

cd examples/smart_home
sparx run

# 通过 MCP 服务控制灯光、温度、安防

📡 IoT 边缘 Agent

cd examples/iot_edge
sparx run --low-power

# 针对电池供电设备优化

🔌 部署到 NPU 设备

使用 CPU 推理开发 Agent 后，部署到 Qualcomm NPU 硬件用于生产：

# 列出已连接设备
sparx devices

# 部署到设备
sparx deploy --device 1

# 交互式会话
sparx shell

支持的平台：

平台	SoC	状态	备注
车载	SA8155P	✅ 支持	Gen 3
车载	SA8295P	✅ 支持	Gen 4
车载	SA8650P	✅ 支持	Gen 4+
车载	SA8775P	🔄 测试中	Gen 4
手机	Snapdragon 8 Gen 3	🔄 计划中	2026 Q4
IoT	QCS6490	🔄 计划中	2027

🗺️ 路线图

核心 Agent 框架 (v2.0)
Qualcomm QNN NPU 集成
MCP 服务编排
WAL 恢复 + Unknown 终态
CLI 工具 (init/run/deploy/doctor/plan)
多模态输入（摄像头、LiDAR、雷达）— 2026 Q3
分布式 Agent 编排 — 2026 Q4
端云混合模式 — 2027
更多平台（NVIDIA Jetson、Rockchip）— 2027

📚 文档

系统概述 — 架构深度解析
构建和测试 — 编译指南
WAL 恢复机制 — 崩溃恢复原理
MCP 服务 — 如何添加自定义能力
Qualcomm NPU — QNN SDK 集成指南

❓ 常见问题

我需要 Qualcomm 硬件才能使用 Sparx 吗？

不需要。Sparx 可以在任何 Mac/Linux/Windows 机器上使用 CPU 推理（llama.cpp）运行。Qualcomm NPU 是可选的，用于需要 <100ms 延迟的生产部署。

支持哪些模型？

任何 llama.cpp 兼容的 GGUF 模型（Qwen2-4B、Qwen3-4B、Llama、Mistral 等）。NPU 部署需要将模型转换为 QNN 格式。

这是生产可用的吗？

是的。v2.0 核心已在车载场景测试，包含 15 个测试套件覆盖崩溃恢复、并发和故障注入。目前已部署在基于 SA8295P 的车辆上。

WAL 恢复如何工作？

Sparx 在执行前记录每个有副作用的操作（API 调用、支付、设备控制）。如果 Agent 在操作中途崩溃，它会以三种可能状态恢复：COMMITTED（成功）、FAILED（错误）或 UNKNOWN（崩溃前状态未知）。UNKNOWN 需要手动对账以防止静默失败。

可以用于非车载应用吗？

绝对可以。虽然展示的 demo 是车载的，但 Sparx 适用于任何端侧 Agent 场景：智能家居、IoT、机器人、医疗设备、工业自动化等。

🤝 贡献指南

欢迎贡献！请查看 CONTRIBUTING_zh-CN.md 了解详情。

新手友好 Issue： https://github.com/OpenSparX/MasterAgent/labels/good%20first%20issue

💬 社区

讨论区：GitHub Discussions
问题反馈：GitHub Issues
邮箱：dev@openschbrid.com

📄 许可证

Apache 2.0 — 详见 LICENSE

Try it now · 立即尝试 — install and run in 60 seconds / 60 秒安装运行：

npm install -g @sparx/cli && sparx demo automotive

Name		Name	Last commit message	Last commit date
.github		.github
app		app
cli		cli
cmake		cmake
config		config
demo		demo
docs		docs
examples		examples
include/master_agent		include/master_agent
packaging		packaging
scripts		scripts
src		src
tests		tests
third_party		third_party
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CMakeLists.txt		CMakeLists.txt
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTING_zh-CN.md		CONTRIBUTING_zh-CN.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
VERSION.json		VERSION.json

Latest commit

History

Folders and files

Repository files navigation

是什么

🚀 Why On-Device Agents?

🎬 See It in Action

🏗️ Architecture

💎 What Makes Sparx Different?

1. Unknown Terminal State — Industry First

2. Deterministic-First Routing

3. Optional NPU Acceleration

⚡ Quick Start

Install

Create Your First Agent

Build Execution Plans

📦 Examples

🚗 Automotive Voice Assistant

🏠 Smart Home Control

📡 IoT Edge Agent

🔌 Deploy to NPU Devices

🗺️ Roadmap

📚 Documentation

❓ FAQ

🤝 Contributing

💬 Community

📄 License

⚡ Sparx

🚀 为什么选择端侧 Agent？

🎬 实际演示

🏗️ 架构

💎 Sparx 的独特之处

1. Unknown 终态 — 业界首创

2. 确定性优先路由

3. 可选 NPU 加速

⚡ 快速开始

安装

创建第一个 Agent

构建执行计划

📦 示例项目

🚗 车载语音助手

🏠 智能家居控制

📡 IoT 边缘 Agent

🔌 部署到 NPU 设备

🗺️ 路线图

📚 文档

❓ 常见问题

🤝 贡献指南

💬 社区

📄 许可证

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages