OpenSparX/MasterAgent

OpenSparX / MasterAgent – 작고 임베드 가능한 C++ 에이전트 런타임

개요

• 로컬 우선 AI 에이전트를 구축할 수 있는 오픈 소스 C++17 라이브러리(및 CLI)입니다. 사용자의 발화를 결정론적인 정확한 구문 기술(모델 불필요)과 먼저 매칭합니다. 기술이 매칭되지 않으면 간단한 HTTP/JSON API를 통해 로컬에서 호스팅되는 LLM(예: llama-server)으로 요청을 전달할 수 있습니다.
• 런타임은 도구 정의(이름, 인자용 JSON 스키마)를 검증하며, 선언된 도구만 호출되고 매개변수가 확인되도록 보장합니다. 도구 결과는 구조화된 JSON 형태로 호출자에게 반환됩니다.
• 완전히 오프라인(libcurl 및 SQLite 없이)으로 실행하거나, 모델 호출을 위한 선택적 HTTP 지원 및 영구 요청 영수증을 위한 선택적 SQLite 저장소를 사용하여 실행할 수 있습니다.

주요 기능

기능	작동 방식
정확한 구문 기술	미리 등록된 구문이 결정론적 콜백을 트리거하여 모델을 우회합니다.
도구 등록 및 검증	개발자는 JSON 스키마와 유사한 설명과 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++에서 각 도구를 이름, 매개변수 스키마, 실제 작업을 수행하는 콜백(예: 자동차 에어컨 컨트롤러와 통신)으로 등록합니다.
2. 정확한 구문 기술 추가 – 고정된 사용자 발화(예: "把空调调到22度")를 적절한 도구를 호출하는 콜백에 매핑합니다.
3. 빌드 – cmake -S . -B build -DCMAKE_BUILD_TYPE=Release(HTTP 어댑터를 제거하려면 -DMASTER_AGENT_ENABLE_HTTP=OFF, SQLite를 제거하려면 -DMASTER_AGENT_ENABLE_STORAGE=OFF 추가).
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에서 직접 가져온 것이며, 추가 기능은 추론되지 않았습니다.