BoxAgnts 소개 (4) — 핵심 아키텍처 (Core Architecture) - Insights | Molayo

이전 세 편의 기사에서는 BoxAgnts의 3계층 아키텍처 (three-tier architecture) 중 각 계층을 하나씩 분석했습니다.

외부 계층 (Outer layer): 즉시 사용 가능한 사용자 경험 (Out-of-the-box user experience) — Vue 3 대시보드 (Dashboard), REST API, WebSocket 실시간 통신 (real-time communication)
중간 계층 (Middle layer): 에이전트 툴박스 (Agent Toolbox) — 멀티 모델 디스패치 (multi-model dispatch) (LlmProvider trait), 에이전트 추론 루프 (Agent reasoning loop), 도구 트레이트 (Tool trait) 통합 추상화, Cron 스케줄링 (Cron scheduling)
하단 계층 (Bottom layer): WASM 보안 샌드박스 (WASM security sandbox) — Wasmtime 엔진, 11차원 실행 옵션 (11-dimensional RunOption), 3계층 심층 방어 (three-layer defense-in-depth)

하지만 아키텍처의 진정한 가치는 각 계층이 개별적으로 무엇을 하는가가 아니라, 이들이 어떻게 협업하느냐에 달려 있습니다. 이 기사에서는 다섯 가지 관점을 통해 이러한 협업을 살펴봅니다.

3계층 파노라마 (Three-Layer Panorama)

┌──────────────────────────────────────────────────────────────────┐
│                        OUTER LAYER                               │
│                                                                  │
...

세 가지 핵심 인터페이스: 아키텍처의 "관절 (Joints)"

계층형 아키텍처 (layered architecture)가 뛰어난지 여부는 계층 간 인터페이스 (inter-layer interfaces)에 달려 있습니다. BoxAgnts는 인체의 관절처럼 각 계층을 연결하는 세 가지 명확한 인터페이스를 정의합니다.

인터페이스 1: 외부 계층 ↔ 중간 계층 — HTTP + WebSocket

이것은 사용자 상호작용 (user interaction)과 비즈니스 로직 (business logic) 사이의 경계입니다:

Dashboard (Vue 3)
    │
    ├── REST API (Axum) ──→ gateway/api/chat.rs, config.rs, cron.rs...
...

주요 설계 결정: 채팅 명령 전송과 응답 수신은 두 가지 서로 다른 채널을 사용합니다:

명령 전송 (Command sending): WebSocket (저지연, 양방향)
스트리밍 응답 (Streaming responses): WebSocket 푸시 QueryEvent (실시간, 단방향)
이력 로딩 (History loading): REST API (멱등성, 캐싱 가능)

이러한 분리는 REST의 롱 폴링 (long-polling) 문제를 방지하며, WebSocket이 모든 데이터를 부담하게 만드는 것도 방지합니다.

인터페이스 2: 중간 계층 ↔ 하단 계층 — 도구 트레이트 (Tool Trait)

이것은 비즈니스 로직과 보안 실행 (secure execution) 사이의 경계입니다. 또한 가장 중요한 인터페이스이기도 합니다:

pub trait Tool: Send + Sync {
    fn name(&self) -> &'static str;                          // AI에게 노출됨
    fn description(&self) -> &'static str;                   // AI에게 노출됨
...

이 인터페이스의 우아함은 비대칭 정보 설계 (asymmetric information design)에 있습니다:

인터페이스 메서드 (Interface Method)	사용 주체 (Used By)	목적 (Purpose)
`name()`	AI 모델 (AI Model)	시스템 프롬프트에 도구 이름 목록 나열
...

AI 모델은 처음 세 가지만 확인하면 됩니다. 도구가 어디에서 실행되는지(Rust 또는 WASM)는 알 필요가 없습니다. 이는 정보 은닉 (information hiding) 원칙을 완벽하게 구현합니다.

인터페이스 3: 하위 레이어 ↔ 시스템 리소스 — WASI

이것은 보안 샌드박스 (security sandbox)와 호스트 운영체제 (host operating system) 사이의 경계입니다:

WASM 컴포넌트 (WASM Component)
    │
    ├── fopen("/src/main.rs") ──→ WASI preopen ──→ 호스트 /workspace/src/main.rs
...

WASI는 WebAssembly 표준화 기구에서 정의한 인터페이스 사양이며, 모든 주요 WASM 런타임 (runtimes)에서 지원됩니다. 커스텀 인터페이스 대신 WASI를 선택했다는 것은 BoxAgnts의 샌드박스 컴포넌트가 런타임 간 이식성 (cross-runtime portability)을 갖게 됨을 의미합니다.

전체 요청 추적: 사용자 입력부터 샌드박스 실행까지

세 가지 레이어를 모두 통과하는 전체 사용자 요청을 추적해 보겠습니다:

⌨️  사용자가 ChatPage에 입력함:
    "프로젝트 내에 사용자를 위한 전체 CRUD 기능이 포함된 REST API 엔드포인트를 생성하도록 도와줘"

...

디자인 패턴 및 아키텍처 트레이드오프 (Architectural Trade-offs)

패턴 1: 관심사의 분리 (Separation of Concerns)

관심사 (Concern)	레이어 (Layer)	독립적 진화 (Independent Evolution)
사용자 경험, 시각화, 상호작용	외부 (Outer)	프론트엔드를 React / Tauri / Flutter로 전환 가능
...

패턴 2: 인터페이스 지향 프로그래밍 (Interface-Oriented Programming)

Tool 트레이트 (trait)는 전체 구조물의 초석입니다. 이는 Rust 네이티브 도구와 WASM 샌드박스 도구에 정확히 동일한 인터페이스 형태를 부여합니다. 이 설계의 이점은 다음과 같습니다:

AI 모델은 도구가 어떻게 구현되었는지 알 필요가 없습니다.
중간 계층 (Middle layer)은 하단이 Rust인지 WASM인지 신경 쓸 필요가 없습니다.
하단 계층 (Bottom layer)은 중간 계층에 영향을 주지 않고 독립적으로 최적화될 수 있습니다.

패턴 3: 내장된 보안 (Embedded Security)

BoxAgnts의 보안 메커니즘은 단순히 "덧붙여진(bolt-on)" 것이 아니라, 아키텍처에 깊숙이 내장되어 있습니다:

외부 계층 (Outer layer) 인증 확인 (로컬 vs 원격)
하단 계층 (Bottom layer) 3단계 방어 (리소스 + WASI + 네트워크)
인터페이스 계층 (Interface layer) 파라미터 검증 (input_schema에 정의된 JSON Schema)

트레이드오프 (Trade-off): WASM 선택에 따른 비용

장점	비용	BoxAgnts의 처리 방식
명령 수준의 보안 격리 (Instruction-level security isolation)	WASM 컴포넌트 개발/디버깅의 복잡성	핵심 작업(Core ops)은 WASM을 사용하고, 메타 작업(Meta ops)은 Rust 네이티브를 사용함
...

이러한 실용적인 트레이드오프는 성숙한 엔지니어링적 판단을 반영합니다. 즉, "순수성"을 위해 유연성을 희생하지도, "편의성"을 위해 보안을 희생하지도 않습니다.

핵심 아키텍처 통찰 (Core Architectural Insights)

통찰 1: 좋은 아키텍처는 "단순한 것은 단순하게, 복잡한 것은 가능하게" 만듭니다.

단순한 시나리오: 그냥 채팅만 하고 싶다면?
→ boxagnts → 브라우저 열기 → 질문 입력 → 채팅
→ 내부적으로 세 개의 계층은 보이지 않으며, 설정이 전혀 필요 없음
...

통찰 2: 인터페이스는 아키텍처의 관문입니다.

세 가지 핵심 인터페이스 (HTTP/WS, Tool trait, WASI)는 세 개의 관문입니다. 이 인터페이스들의 계약(Contract)이 유지되는 한, 각 계층은 내부적으로 자유롭게 리팩토링될 수 있습니다:

프론트엔드를 Vue 3에서 React로 변경 — 백엔드에 영향을 주지 않음 (HTTP API 변경 없음)
AI 모델을 Anthropic에서 OpenAI로 변경 — 도구에 영향을 주지 않음 (Tool trait 변경 없음)
샌드박스 엔진을 Wasmtime에서 WasmEdge로 변경 — 비즈니스에 영향을 주지 않음 (WASI 표준 변경 없음)

통찰 3: 보안은 신뢰의 화폐입니다.

AI가 파일을 조작하고, 명령을 실행하며, 네트워크에 접속할 수 있는 시대에:

보안이 없으면 = 신뢰가 없습니다.
신뢰가 없으면 = 깊이 있게 사용할 사용자가 없습니다.
보안을 아키텍처의 최하단에 배치한다는 것은, 보안이 우회되거나 간과될 수 없음을 의미합니다.

인사이트 4: 통합 추상화 (Unified Abstraction)를 통한 복잡성 감소

BoxAgnts의 아키텍처에는 반복되는 패턴이 있습니다. 바로 하나의 핵심 추상화 (Abstraction)를 사용하여 다양한 구현체들을 통합하는 것입니다.

멀티 모델 (Multi-model) → LlmProvider 트레이트 (trait) → 하나의 인터페이스, 20개 이상의 구현체
멀티 툴 (Multi-tool) → Tool 트레이트 (trait) → 하나의 인터페이스, Rust + WASM 구현체
멀티 스토리지 (Multi-storage) → 워크스페이스 (workspace) → SQLite (상태) + JSON (설정)
...

이러한 "통합 추상화 (Unified Abstraction)" 설계는 인지 부하 (Cognitive load)를 줄여줍니다. 개발자는 전체 시스템을 숙달하기 위해 단 몇 가지 핵심 개념만 이해하면 됩니다.

다른 AI 에이전트 시스템과의 비교

차원 (Dimension)	LangChain/LangGraph	AutoGPT	BoxAgnts
설치 경험 (Install Experience)	pip install + 설정 (config)	Docker + 설정 (config)	단일 파일 다운로드 및 실행
...

BoxAgnts의 독특한 포지셔닝은 AI 에이전트를 구축하기 위한 개발 프레임워크 (Development framework) (이는 LangChain의 영역입니다)가 아니라, **즉시 사용 가능한 AI 에이전트 런타임 플랫폼 (Ready-to-use AI Agent runtime platform)**이라는 점에 있습니다.

AI 툴 개발자를 위한 교훈

자신만의 AI 에이전트 시스템을 개발하고 있다면, BoxAgnts의 3계층 설계는 다음과 같은 교훈을 제공합니다.

1. 기능을 구현하기 전에 인터페이스를 먼저 정의하라

Tool 트레이트 (trait)는 BoxAgnts의 핵심 골격입니다. 모든 확장 기능은 이 트레이트를 중심으로 회전합니다. 새로운 툴은 단순히 이를 구현하기만 하면 되며, 새로운 기능은 에이전트 루프 (Agent loop)에 의해 자동으로 인식됩니다. 좋은 트레이트를 설계하는 데 소비하는 시간은 장기적인 확장성 (Extensibility)으로 보상받습니다.

2. 첫날부터 보안을 고려하라

샌드박스 (Sandbox)를 추가하기 위해 문제가 발생할 때까지 기다리지 마십시오. 그때가 되면 아키텍처는 이미 고정되어 있으며, 보안은 단지 "패치 (Patch)"로서만 존재할 수 있습니다. BoxAgnts는 처음부터 보안을 최하단에 배치했으며, 이는 어떤 새로운 기능이라도 자동으로 샌드박스 보호를 받게 됨을 의미합니다.

3. 통합 추상화로 복잡성을 줄여라

기능의 유형에 따라 서로 다른 인터페이스를 설계하지 마십시오. 하나의 트레이트 (trait)가 모든 것을 통제합니다. Vec<Box<dyn Tool>>은 호출자 입장에서 차이 없이 단순한 툴 (SleepTool)과 복잡한 툴 (WasmTool)을 동시에 보유합니다.

4. 사용자의 선택지를 최소화하라

6개의 CLI 파라미터 > 60줄의 YAML 설정. 모든 파라미터에는 합리적인 기본값이 설정되어 있습니다. 사용자는 "도구를 설정하는 것"이 아니라 "문제를 해결하기 위해 도구를 사용하는 것"에 시간을 써야 합니다.

5. 각 계층은 오직 자신의 문제에만 집중한다

외부 계층(Outer layer)은 하단에서 Wasmtime을 사용하는지 Docker를 사용하는지 신경 쓰지 않습니다.
중간 계층(Middle layer)은 외부에서 Vue를 사용하는지 React를 사용하는지 신경 쓰지 않습니다.
하단 계층(Bottom layer)은 중간에서 어떤 AI 모델을 사용하는지 신경 쓰지 않습니다.
각 계층은 인접한 계층과의 인터페이스(Interface)만 이해하면 됩니다.

6. 실용적인 기술적 트레이드오프 (Technical Trade-offs)

모든 작업이 반드시 WASM 샌드박스(Sandbox)를 거칠 필요는 없습니다. AskUserQuestion은 순수한 UI 상호작용이며, PlanMode는 순수한 상태 관리(State management)입니다. BoxAgnts는 Rust 네이티브 도구와 WASM 도구가 동일한 all_tools() 리스트 내에서 공존할 수 있게 합니다. 이는 교조적인 고집이 아닌 실용적인 선택입니다.

3계층 시너지의 가치 공식

단일 계층의 가치:
  외부 계층(Outer) = 좋은 사용자 경험 (User experience)
  중간 계층(Middle) = 강력한 기능 (Capabilities)
...

결론

BoxAgnts의 3계층 아키텍처는 복잡한 개념이 아닙니다. 단 세 가지만 수행합니다:

외부 계층 (Outer layer): 사용자가 AI와 쉽게 상호작용할 수 있게 합니다 — 6개의 파라미터, 10개의 페이지, 1개의 대시보드(Dashboard)
중간 계층 (Middle layer): AI가 도구와 지식을 유연하게 배분할 수 있게 합니다 — 1개의 트레이트(Trait), 20개 이상의 모델, 6개의 모듈
하단 계층 (Bottom layer): 모든 작업이 안전한 환경에서 실행되도록 합니다 — 1개의 엔진, 11차원 제어, 3계층 방어

하지만 이 세 가지가 유기적으로 결합될 때 비로소 완전하고, 신뢰할 수 있으며, 확장 가능한 AI 에이전트(Agent) 플랫폼이 형성됩니다.

세 계층은 각각의 역할을 수행하면서 정밀하게 정의된 인터페이스를 통해 긴밀하게 협력합니다. HTTP/WebSocket은 외부와 중간 계층을 연결하고, Tool 트레이트(Trait)는 중간과 하단 계층을 연결하며, WASI는 하단 계층과 시스템 리소스를 연결합니다. 이 세 가지 인터페이스는 세 개의 관문과 같습니다. 이 관문들을 지키는 것이 곧 아키텍처의 안정성과 진화 가능성을 확보하는 것을 의미합니다.

프로젝트의 이름이 암시하듯 — Box (도구 상자), Agent (지능형 에이전트), Sandbox (샌드박스) — 세 개의 단어, 세 개의 계층, 그리고 하나의 완전한 AI 에이전트 (AI Agent) 런타임 플랫폼을 의미합니다.

BoxAgnts 소개 (4) — 핵심 아키텍처 (Core Architecture)

요약

핵심 포인트