OpenSparX/MasterAgent

OpenSparX / MasterAgent – 一个轻量级、可嵌入的 C++ 代理运行时

它是什么

• 一个开源的 C++17 库（及配套的 CLI），让您能够构建本地优先的 AI 代理。它首先将用户的语句与一组确定性的精确短语技能进行匹配（无需模型）。如果未匹配到技能，它可以将请求通过简单的 HTTP/JSON API 转发给本地托管的 LLM（例如 llama-server）。
• 运行时会验证工具定义（名称、参数的 JSON schema），并确保仅调用已声明的工具，同时检查参数。工具结果会以结构化 JSON 的形式返回给调用者。
• 它可以完全离线运行（无需 libcurl、无需 SQLite），或通过可选的 HTTP 支持进行模型调用，以及可选的 SQLite 存储来实现持久化请求收据。

关键能力

功能	运作方式
精确短语技能	预先注册的短语会触发确定性回调，绕过任何模型。
工具注册与验证	开发者提供类似 JSON-schema 的描述与 C++ 回调；运行时会在执行前检查工具名称与参数。
本地模型集成	当使用 MASTER_AGENT_ENABLE_HTTP=ON 构建时，CLI 可以与任何实现 OpenAI 兼容 /v1/chat/completions 端点的服务器通信（例如运行 GGUF 模型的 llama-cpp 服务器）。
持久化请求收据	启用 SQLite 后，每个请求都会获得一个唯一 ID；重复的调用会被去重，结果会被重播，从而实现崩溃恢复与 UNKNOWN 状态的手动调节。
上下文与取消	每个工具调用都会接收会话 ID、请求 ID、幂等键、截止时间与协作取消令牌。
CLI 与 SDK	sparx 命令行工具展示了流程；SDK 可通过 CMake 安装并链接为 MasterAgent::Core（以及可选的 MasterAgent::Http）。
可扩展示例	参考的“库存代理”展示了如何调用外部 HTTP 服务、提交幂等收据，以及从丢失的响应中恢复。
测试与评估	CI 运行单元测试、合成评估，以及一个构建 SDK、CLI 与示例消费者的打包脚本。

典型工作流程

1. 定义工具 – 在 C++ 中注册每个工具，包含名称、参数 schema 与执行实际工作的回调（例如与汽车空调控制器对话）。
2. 添加精确短语技能 – 将固定的用户语句（例如 "把空调调到22度"）映射到调用适当工具的回调。
3. 构建 – cmake -S . -B build -DCMAKE_BUILD_TYPE=Release（添加 -DMASTER_AGENT_ENABLE_HTTP=OFF 以移除 HTTP 适配器，-DMASTER_AGENT_ENABLE_STORAGE=OFF 以移除 SQLite）。
4. 运行 – ./build/cli/sparx run --input '把空调调到22度'。运行时会匹配短语、验证工具、运行回调并打印 JSON 收据。
5. 可选模型 – 如果没有精确短语匹配，启动本地 LLM 服务器并使用 --endpoint 127.0.0.1:8080 --model local 调用 CLI。模型必须返回 JSON 格式的工具调用或纯 JSON 响应；格式错误的输出将被拒绝。
6. 持久化与恢复 – 提供 --state ./state/agent.db --session alice --request-id ac-001 将收据存储于 SQLite。崩溃后，sparx recover --state ./state/agent.db 会重播成功的结果，并将未完成的结果标记为 UNKNOWN 以供手动调节。

为何重要

• 确定性优先 – 通过在无需模型的情况下处理已知指令，系统避免了幻觉并保证了可重复的行为。
• 安全性 – 工具名称与参数经过严格验证；运行时绝不会从随机的模型输出中猜测工具调用。
• 本地优先 – 不需要云服务；一切都可以在笔记本电脑、边缘设备或容器内运行。
• 持久性 – SQLite 收据提供了简单的审计轨迹，并为关键业务操作（例如库存扣减）实现了“仅执行一次”的语义。

入门指南

# Clone and build (Ubuntu example)
git clone https://github.com/OpenSparX/MasterAgent.git
cd MasterAgent
sudo apt-get install libcurl4-openssl-dev libsqlite3-dev   # optional deps
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 4
ctest --test-dir build --output-on-failure

# Run the demo (no model needed)
./build/cli/sparx demo automotive
./build/cli/sparx run --input '把空调调到22度'

许可 – Apache-2.0。

---

以上所有细节均直接取自仓库的 README；未推论出任何额外功能。