agent.cpp: Mozilla AI가 공개한 C++ 기반의 경량 로컬 LLM 에이전트 프레임워크

읽을거리&정보공유
, , , ,
1

agent.cpp: Mozilla AI가 공개한 C++ 기반의 경량 로컬 LLM 에이전트 프레임워크
agent.cpp: Mozilla AI가 공개한 C++ 기반의 경량 로컬 LLM 에이전트 프레임워크1128×324 20 KB

agent.cpp 소개

agent.cpp는 Mozilla AI에서 개발한 C++ 기반의 LLM 에이전트 구축 라이브러리입니다. 이 프로젝트는 **로컬 환경(Local)**에서 소형 언어 모델(SLM)을 활용하여 에이전트를 구동하는 데 초점을 맞추고 있으며, 추론 엔진으로 llama.cpp를 핵심 구성 요소로 사용합니다.

최근의 AI 에이전트 개발이 대부분 Python 생태계(LangChain, AutoGen 등)나 외부 클라우드 API에 의존하는 것과 달리, agent.cpp는 외부 API 호출 없이 로컬 장비에서 완전히 독립적으로 동작하는 에이전트를 C++로 구현할 수 있게 해줍니다. 이는 인터넷 연결이 없는 환경이나 고성능이 요구되는 엣지 디바이스, 임베디드 시스템에서 AI 에이전트를 통합하려는 개발자들에게 적합합니다.

agent.cpp 라이브러리는 단순히 텍스트를 생성하는 것을 넘어, 모델이 '도구(Tools)'를 사용하고, 작업을 반복(Loop)하며, 콜백(Callbacks)을 통해 시스템과 상호작용하는 에이전트 패턴을 C++ 표준(C++17 이상) 환경에서 제공합니다. 개발자는 이를 통해 시스템 쉘 명령을 실행하거나, 메모리를 관리하고, 복잡한 작업을 수행하는 다중 에이전트(Multi-Agent) 시스템을 구축할 수 있습니다.

agent.cpp vs. llama.cpp 및 Python 프레임워크와의 비교

agent.cpp의 위치를 명확히 이해하기 위해 다른 기술들과 비교해 볼 수 있습니다.

먼저 llama.cpp와 비교를 해보면, llama.cpp는 LLM의 '두뇌' 역할을 하는 추론 엔진입니다. 모델 파일(GGUF)을 로드하고 텍스트를 생성하는 raw level의 기능을 제공합니다. 이에 비해, agent.cpp는 llama.cpp를 내장하여 그 위에 행동을 얹은 프레임워크입니다. 모델이 언제 도구를 사용해야 하는지 판단하고, 도구 실행 결과를 다시 모델에 입력하는 '루프(Loop)'와 '상태 관리' 기능을 제공합니다.

다음으로 LangChain/LlamaIndex와 같은 프레임워크와 비교를 해보겠습니다. 이러한 Python 기반 프레임워크는 프로토타이핑이 빠르고 생태계가 방대하지만, 배포 시 무거운 Python 런타임이 필요하며 실행 속도나 메모리 효율성 면에서 네이티브 C++보다 불리할 수 있습니다. 하지만 agent.cpp는 C++ 프로젝트에 직접 통합(CMake)할 수 있어, 가볍고 빠른 실행이 가능하며 기존 C++ 애플리케이션(게임 엔진, 데스크톱 앱 등)에 AI 기능을 이식하기에 최적화되어 있습니다. 외부 API 호출을 위한 것이 아니라는 점이 가장 큰 차이입니다.

agent.cpp의 주요 기능

agent.cpp는 에이전트를 구성하기 위해 다음과 같은 5가지 핵심 빌딩 블록을 정의합니다.

에이전트 루프 (Agent Loop)

에이전트의 핵심 실행 흐름입니다. 일반적인 LLM 에이전트와 마찬가지로, 종료 조건이 충족될 때까지 모델 호출과 도구 실행을 반복합니다. 에이전트 루프 내에서 기본적으로는 모델이 도구 실행 없이 텍스트 응답만 생성하면 루프가 종료됩니다. 개발자는 콜백을 통해 커스텀 종료 조건을 추가할 수 있습니다.

도구 (Tools)

에이전트 루프 내에서 모델이 텍스트 생성 이외의 작업을 수행할 수 있도록 기능을 확장합니다. 각 도구는 다음 요소를 포함합니다:

  • 이름 및 설명 (Name & Description): 모델이 언제 이 도구를 사용해야 할지 판단하는 기준이 됩니다.
  • 파라미터 스키마 (Parameters Schema): JSON Schema를 사용하여 도구 실행에 필요한 인자(Arguments)의 형식을 정의합니다.
  • 실행 함수 (Execute Function): 실제 C++ 코드로 구현된 동작입니다.

즉, 모델이 도구 사용을 결정하면, 에이전트는 이를 파싱하고 실행한 뒤 결과를 대화 맥락(Context)에 다시 포함시킵니다.

모델 (Model)

로컬 LLM 초기화 및 추론을 담당하는 래퍼(Wrapper)입니다. 이 부분은 llama.cpp와 강하게 결합되어 있으며, GGUF 형식의 모델 파일이 필요합니다. 대화 템플릿 적용, 토큰화(Tokenization), 샘플링 파라미터(Temperature, top_p 등) 설정, KV 캐시 관리 등을 자동으로 처리합니다.

예제 코드에서는 granite-4.0-micro와 같은 경량 모델을 기본으로 사용합니다.

콜백 (Callbacks)

에이전트 수명 주기의 특정 지점에 개발자가 개입할 수 있는 훅(Hook)을 제공합니다. agent.cpp가 제공하는 훅(hook) 및 콜백 시점은 다음과 같습니다:

  • before_agent_loop / after_agent_loop: 에이전트 루프 시작/종료 시점
  • before_llm_call / after_llm_call: 모델 추론 전/후 (메시지 가로채기 또는 수정 가능)
  • before_tool_execution / after_tool_execution: 도구 실행 전/후 (실행 검증 또는 결과 처리)

이러한 콜백 기능을 통해 로깅, 디버깅(Tracing), 문맥 조작, 사용자 승인(Human-in-the-loop) 절차 등을 구현할 수 있습니다.

지시사항 (Instructions)

에이전트의 행동과 능력을 정의하는 시스템 프롬프트(System Prompt) 입니다. 에이전트 생성자에 전달되며, 모든 대화의 시작 부분에 자동으로 추가됩니다.

agent.cpp의 설치 및 사용

agent.cpp는 C++17 또는 그 이상이 필요하며, 3가지 방법으로 사용할 수 있습니다.

첫번째 방법은 CMake를 사용하는 C++ 프로젝트라면 FetchContent를 통해 쉽게 통합할 수 있습니다. 다음과 같이 추가해주세요:

include(FetchContent)
FetchContent_Declare(
    agent-cpp
    GIT_REPOSITORY https://github.com/mozilla-ai/agent.cpp
    GIT_TAG main
)
FetchContent_MakeAvailable(agent-cpp)
target_link_libraries(my_app PRIVATE agent-cpp::agent)

하드웨어 가속(CUDA 등)을 사용하려면 빌드 시 llama.cpp와 동일한 CMake 플래그를 전달하면 됩니다:

# NVIDIA GPU용 CUDA
cmake -B build -DGGML_CUDA=ON

# CPU용 OpenBLAS
cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS


또 다른 방법으로는 agent.cpp 프로젝트를 직접 빌드 및 설치한 다음, find_package를 사용하는 방법입니다. 먼저 빌드 및 설치는 다음과 같이 가능합니다:

# 저장소 복제 및 cmake를 사용한 빌드
git clone --recursive https://github.com/mozilla-ai/agent.cpp
cd agent.cpp
cmake -B build -DAGENT_CPP_INSTALL=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build

# 설치 (--prefix 를 사용하여 설치 위치 지정 가능)
cmake --install build --prefix ~/.local/agent-cpp

이후 다음과 같이 사용합니다:

# If installed to a custom prefix, tell CMake where to find it
list(APPEND CMAKE_PREFIX_PATH "~/.local/agent-cpp")

find_package(agent-cpp REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE agent-cpp::agent)


마지막은 Git Submodule을 사용하는 방법입니다. 다음과 같이 agent.cpp를 Git Submodule로 추가한 뒤 직접 호출하면 됩니다:

# Git Submodule 추가
git submodule add https://github.com/mozilla-ai/agent.cpp agent.cpp
git submodule update --init --recursive

# 프로젝트에 직접 추가
add_subdirectory(agent.cpp)
target_link_libraries(my_app PRIVATE agent-cpp::agent)

라이선스

agent.cpp 프로젝트는 MIT 라이선스로 공개 및 배포되고 있습니다.

:github: agent.cpp 프로젝트 GitHub 저장소



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck:

1개의 좋아요