OAK 本地智能体运行时

这个 Agent 能做什么，适合哪些场景？

OAK / MasterAgent 是一个 C++17 本地优先运行时，提供可构建的 sparx 命令行工具和可安装的 C++ SDK。master_agent::reference API 允许应用注册工具、参数模式、回调和精确短语技能；运行时先匹配确定性技能，再按需请求模型。它会校验工具名和参数，并返回实际工具结果；未匹配输入在未配置模型时返回 NO_ROUTE。默认只在内存中保存会话状态；显式启用 SQLite 后，可持久化执行回执和历史以支持重启后的请求去重及中断恢复。该参考运行时不提供 Qualcomm QNN/Genie 集成，相关平台接入需要自行完成。

通过 sparx demo automotive，运行模拟车载空调的内存演示：设置温度并读取结果，输出 JSON。用 sparx run --input ... 可处理单次输入；持续运行时可逐行输入并在同一进程保留演示状态。运行时先检查已注册的精确短语技能，再调用可选模型回调或本地模型 HTTP 适配器；模型可返回 JSON 或单个工具调用，工具名及参数必须通过校验后才执行。可通过 --state、--session 和 --request-id 启用 SQLite 回执与历史，重复请求会返回记录结果；未完成请求会标记为 UNKNOWN，需核验并显式对账。SDK 也支持上下文工具，其执行上下文包含请求身份、稳定幂等键、截止时间和协作式取消信号。

1. 汽车软件团队可用 sparx demo automotive 原型验证本地车载控制流程，无需真实车辆或模型。
2. 嵌入式 C++ 开发者可将 MasterAgent::Core 集成到应用中，注册受参数模式约束的业务工具。
3. 需要本地推理的团队可连接单独运行的 llama-server，并通过 HTTP 适配器请求工具调用。
4. 需要跨进程请求去重的业务应用可启用 SQLite，并在进程重启后恢复执行回执和历史。
5. 库存系统开发者可参考 inventory example，对接独立 HTTP 服务并演练丢失响应后的 UNKNOWN 恢复与对账。

如何安装或部署这个 Agent？

需要 CMake 3.18+、C++17；启用 HTTP 适配器时需要 libcurl 开发文件，启用持久化时需要 SQLite 开发文件。测试和打包需要 Python 3。仓库提供 Linux 和 macOS 发布 CI 目标。

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-failure

Ubuntu 上 HTTP 和 SQLite 依赖可按 README 安装：

sudo apt-get install libcurl4-openssl-dev libsqlite3-dev

无需 libcurl 的 SDK 和确定性 CLI 构建方式：

cmake -S . -B build-offline -DMASTER_AGENT_ENABLE_HTTP=OFF -DBUILD_EVAL=OFF
cmake --build build-offline --parallel 4

如需省去两个可选依赖：

cmake -S . -B build-minimal -DMASTER_AGENT_ENABLE_HTTP=OFF -DMASTER_AGENT_ENABLE_STORAGE=OFF
cmake --build build-minimal --parallel 4

如何使用这个 Agent？

先运行内存模拟演示；它不需要模型、凭据、网络或车辆硬件：

./build/cli/sparx demo automotive

用中文或英文输入测试已注册技能：

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

连接自行启动的兼容 llama-server；运行时不会下载或启动模型，也不会自动回退到云端：

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

设置超时和认证时，可将 API 密钥存入环境变量，并传入变量名：

./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'

启用 SQLite 持久化并在重启后检查恢复状态：

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

集成 SDK 时，安装后通过 CMake 查找 MasterAgent，链接 MasterAgent::Core；HTTP 适配器可选链接 MasterAgent::Http。支持的公开入口为 master_agent::reference 中的 reference_runtime.h。

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

最近版本

来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。

1. v2.1.15 2026-08-12
   发布说明摘录

   Full Changelog: https://github.com/OpenSparX/MasterAgent/compare/v2.1.14...v2.1.15

   在 GitHub 查看 ↗
2. v2.1.14 2026-08-12
   发布说明摘录

   Full Changelog: https://github.com/OpenSparX/MasterAgent/compare/v2.1.13...v2.1.14

   在 GitHub 查看 ↗
3. v2.1.6 2026-08-10
   发布说明摘录

   Full Changelog: https://github.com/OpenSparX/MasterAgent/compare/v2.1.5...v2.1.6

   在 GitHub 查看 ↗

常见问题