BoxAgnts 소개 (2) — AI Agent Toolbox

BoxAgnts의 미들웨어 레이어(middle layer)인 Agent Toolbox는 시스템의 두뇌이자 손 역할을 합니다. 이는 사용자의 의도를 이해하고, 적절한 도구를 배정하며, 실행 결과를 피드백하는 세 가지 역할을 수행하는 6개의 핵심 모듈로 구성됩니다. 이 글에서는 각 모듈의 아키텍처 설계와 주요 구현 사항을 심도 있게 살펴봅니다.

아키텍처 개요: 7개 모듈의 협업 네트워크

대시보드(Dashboard)에 "이 Rust 프로젝트의 코드 구조를 분석하는 것을 도와줘"라고 입력하고 전송을 누르면 어떤 일이 일어날까요?

User Message
  │
  ▼
...

각 모듈을 하나씩 분석해 보겠습니다.

boxagnts-api: 통합 멀티 모델 추상화 레이어 (Unified Multi-Model Abstraction Layer)

이 레이어는 미들웨어 레이어와 외부 AI 세계 사이의 인터페이스 레이어입니다. 이는 AI 도구 개발에서 가장 고통스러운 문제, 즉 모든 모델 제공업체의 API가 다르지만, 사용자의 코드가 그 대가를 치러서는 안 된다는 문제를 해결합니다.

LlmProvider 트레이트 (Trait): 다형성 (Polymorphism)의 기초

모든 제공업체 어댑터(provider adapters)가 반드시 구현해야 하는 핵심 인터페이스입니다:

#[async_trait]
pub trait LlmProvider: Send + Sync {
    fn id(&self) -> &ProviderId;       // 고유 식별자 "anthropic", "openai"
...

이 트레이트 설계에는 세 가지 우아한 측면이 있습니다:

1. 비동기 트레이트 (Async trait): Tokio 비동기 런타임(async runtime)과 호환되는 async_trait 매크로를 사용합니다.
2. Pin> 반환: 동적 디스패치(dynamic dispatch)를 사용하여 서로 다른 제공업체의 스트림 타입(stream type) 차이를 추상화합니다.
3. 통합 에러 타이핑 (Unified error typing): 모든 제공업체 에러를 ProviderError로 정규화합니다.

20개 이상의 제공업체를 위한 통합 액세스

BoxAgnts는 매우 광범위한 모델 제공업체를 지원합니다:

카테고리	제공업체 (Providers)	독립 구현 파일
글로벌 메인스트림	OpenAI, Anthropic, Google, Azure, Bedrock	개별 파일
...

핵심 디자인 패턴 — 제공업체(Provider) + 트랜스포머(Transformer) 이중 레이어 아키텍처:

Raw User Message
    │
    ▼
...

ProviderRegistry: 런타임 모델 스위칭 (Runtime Model Switching)

QueryConfig에는 런타임 시 동적인 프로바이더 선택(dynamic provider selection)을 가능하게 하는 provider_registry 필드가 포함되어 있습니다. 이는 다음과 같은 작업이 가능함을 의미합니다:

• 에이전트 설정(Agent config)에서 서로 다른 작업에 대해 서로 다른 모델을 구성 (예: 요약에는 저렴한 모델, 추론에는 강력한 모델 사용)
• 기본 모델(primary model)에 과부하가 걸릴 경우 fallback_model을 사용하여 자동으로 백업 모델로 전환
• ModelRegistry를 통해 여러 모델에 대한 API 키 및 엔드포인트(endpoint) 관리

API Key Management: 보안과 편의성의 균형

BoxAgnts는 각 프로바이더(provider)에 대해 환경 변수 매핑을 미리 정의해 둡:

pub fn api_key_env_vars_for_provider(provider_id: &str) -> &'static [&'static str] {
    match provider_id {
        "anthropic" => &["ANTHROPIC_API_KEY"],
...

이는 환경 변수, 설정 파일, 또는 대시보드(Dashboard) UI라는 세 가지 방법을 통해 API 키를 주입할 수 있음을 의미하며, 보안 경계(security boundaries)를 유지하면서 유연성을 극대화합니다.

boxagnts-query: 에이전트의 핵심 엔진

이 레이어는 BoxAgnts의 절대적인 영혼입니다. run_query_loop() 함수는 약 300줄의 코드로 에이전트의 완전한 추론 루프(reasoning loop)를 구현하며, 놀라울 정도로 많은 예외 케이스(edge cases)를 처리합니다.

Main Loop Skeleton

loop {
    turn += 1;

...

Key Mechanism Analysis

Token Exhaustion Recovery (토큰 소진 복구)

모델이 단일 응답에서 토큰 할당량(token quota)을 모두 소진했을 때, 쿼리 루프는 단순히 잘린 결과를 반환하고 끝내지 않습니다. 대신, 정교하게 설계된 복구 메시지를 자동으로 전송합니다:

"Output token limit hit. Resume directly — no apology, no recap of what
 you were doing. Pick up mid-thought if that is where the cut happened.
 Break remaining work into smaller pieces."

이 메시지는 설계 측면에서 매우 절제되어 있습니다: "사과하지 말 것, 요약하지 말 것, 끊긴 지점부터 이어갈 것, 작업을 세분화할 것" — 최소한의 토큰으로 최대한의 지시 사항을 전달합니다. 무한 루프를 방지하기 위해 최대 3회까지 재시도합니다 (MAX_TOKENS_RECOVERY_LIMIT = 3).

Auto Context Compaction (자동 컨텍스트 압축)

compact.rs는 지능적인 압축 전략 (compression strategy)을 구현합니다. 대화 기록이 모델의 컨텍스트 창 (context window) 제한에 도달하면, 초기 메시지들을 요약하여 핵심 정보(파일 경로, 에러 메시지, 중요한 결정 사항 등)는 보존하면서 불필요한 중간 단계들은 삭제합니다. 이 전략을 통해 전체 코드베이스를 리팩토링하는 것과 같이 매우 복잡한 멀티턴 (multi-turn) 작업에서도 컨텍스트 오버플로 (context overflow)로 인해 에이전트가 "기억을 잃는" 현상을 방지합니다.

Fallback Model Mechanism (폴백 모델 메커니즘)

// query.rs — 과부하 에러 발생 시 백업 모델로 자동 전환
if is_overloaded_error(&err) && fallback_model.is_some() && !used_fallback {
    effective_model = fallback_model;
...

부하가 높은 기간 동안 기본 모델 (예: Claude Sonnet)이 과부하 에러 (overload error)를 반환하면, 시스템은 자동으로 백업 모델 (예: Deepseek)로 전환하여 작업이 중단되지 않도록 보장합니다. 이 메커니즘은 사용자에게 완전히 투명하게(transparent) 작동합니다.

Budget Control (예산 제어)

pub enum QueryOutcome {
    BudgetExceeded { cost_usd: f64, limit_usd: f64 },
    // ...
...

매 턴이 끝날 때마다 쿼리 루프 (query loop)는 누적된 비용이 예산 상한선 (budget cap)을 초과했는지 확인합니다. 모든 API 호출은 모델 및 토큰 소비량을 기록하는 CostTracker를 통해 추적되므로 비용을 제어할 수 있습니다. 예산을 초과할 경우, 조용히 과다 지출하는 대신 명확한 에러 메시지를 반환합니다.

Multimodal Content Blocks (멀티모달 콘텐츠 블록)

ContentBlock 열거형 (enum)은 일반 텍스트부터 심층 사고 (deep thinking)에 이르기까지 상호작용의 모든 범위를 아우르는 14가지 콘텐츠 유형을 정의합니다:

pub enum ContentBlock {
    Text { text: String },                          // 일반 텍스트
    Image { source: ImageSource },                  // 이미지
...

이러한 세밀한 콘텐츠 타이핑 (content typing)을 통해 프론트엔드는 각 유형을 특화된 방식으로 렌더링할 수 있습니다. 예를 들어, 에러 블록은 빨간색 테두리를 표시하고, 작업 할당 블록은 청록색 테두리를 표시하며, 접힌 검색 결과는 단일 행 요약으로 표시됩니다.

Managed Agent Mode (Manager-Executor) (관리형 에이전트 모드)

이것은 BoxAgnts에서 가장 놀라운 미들웨어 (middle-layer) 설계 중 하나입니다. managed_orchestrator.rs는 계층적 에이전트 (Agent) 아키텍처를 구현합니다:

                    User
                      │
                      ▼
...

주요 설정 (Key Configuration)

pub struct ManagedAgentConfig {
    pub enabled: bool,
    pub manager_model: String,           // 매니저 모델 (예: "claude-opus-4-6")
...

시스템 프롬프트 주입 (System Prompt Injection)

매니저 에이전트 (Manager Agent)의 시스템 프롬프트는 그 역할을 정밀하게 정의합니다:

당신은 계획 및 추론 계층인 MANAGER입니다.
당신은 작업을 조정하지만, 파일/bash 도구를 사용하여 직접 작업을 실행하지는 않습니다.
모든 구현 작업은 실행자 에이전트 (executor agents)에게 위임됩니다 (Agent 도구를 통해).
...

실행자 (Executor)의 프롬프트는 "완전한 자기 완결성 (complete self-containment)"을 요구합니다. 즉, 실행자는 매니저의 대화 기록을 볼 수 없으며, 자신의 프롬프트에 모든 컨텍스트를 포함해야 합니다. 이는 컨텍스트 누출 (context leakage)을 방지하고 토큰 소비를 줄여줍니다.

boxagnts-tools + tools-manager: 통합 도구 추상화 (Unified Tool Abstraction)

Tool Trait: 아키텍처의 초석

이것은 BoxAgnts 전체에서 가장 중요한 인터페이스 정의입니다. 모든 새로운 도구는 이 트레이트 (trait)만 구현하면 됩니다:

#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &'static str;
...

ToolContext: 도구의 실행 환경

pub struct ToolContext {
    pub cost_tracker: Arc<CostTracker>,         // 비용 추적기 (Cost tracker)
    pub session_id: Option<String>,             // 세션 ID (Session ID)
...

ToolContext는 도구의 "여권 (passport)" 역할을 하며, 권한, 세션, 비용, 네트워킹과 같은 다양한 컨텍스트 정보를 전달합니다. 모든 도구는 실행 중에 이를 통해 필요한 시스템 상태에 접근할 수 있습니다.

중앙 도구 레지스트리 (Central Tool Registry)

// tools-manager/src/lib.rs
pub fn all_tools() -> Vec<Box<dyn Tool>> {
    vec![
...

Notice that Rust native tools and WASM tools are placed in the same Vec<Box<dyn Tool>> — to the AI model, they are completely equivalent. This is the power of interface-oriented programming.

boxagnts-gateway: Extending Time and Space Dimensions

Cron Scheduled Task Engine

cron/scheduler.rs builds a complete scheduled task system based on tokio_cron_scheduler:

// Core scheduling logic
let cron_job = Job::new_async(cron_expr, move |_uuid, _lock| {
    Box::pin(async move {
...

Key features:

• Timeout protection: Each task has an independent timeout setting (default 180 seconds), wrapped by tokio::time::timeout
• Cancel propagation: On timeout, cancels the executing Agent query via CancellationToken
• Execution logs: Each execution records time, success/failure status, and result summary
• Dynamic management: Tasks can be added, removed, enabled/disabled at any time

Site Hosting System

Site data managed by site/store.rs is persisted via SQLite, supporting CRUD operations. Combined with the frontend SitesPage, users can:

1. Create sites in the Dashboard (enter name and path)
2. Let the AI Agent generate web content
3. Access via the /sites/{name}/ path

boxagnts-workspace: The Agent's Memory System

The workspace module handles all persistence and configuration management:

Function	Storage	Key Implementation
Conversation History	SQLite (rusqlite)	Organized by session, supports CRUD
...
Design highlight: configuration and state are separated. Configuration is JSON files (human-readable and editable), state is SQLite (efficient queries and transactions). This distinction avoids the common pitfall of "configuration file bloat."

QueryConfig: Full-Dimensional Query Control

QueryConfig is a massive configuration struct with 20 fields, covering every dimension of an Agent query:

pub struct QueryConfig {
    pub model: String,                           // Model name
    pub max_tokens: u32,                         // Max output tokens
...

This struct demonstrates a core design philosophy of BoxAgnts: give control to the user, but provide reasonable defaults. Every field can be overridden, but none are required — defaults cover 90% of use cases.

Summary

The middle-layer Agent Toolbox is the capability core of BoxAgnts:

Module	Responsibility	Key Highlight
boxagnts-api	Multi-model unified access	LlmProvider trait, 20+ Providers, Transformer conversion
...

Related Resources

• Boxagnts: https://github.com/guyoung/boxagnts