아키텍처 설계

왜 아키텍처가 중요한가

Agent Harness는 단순한 API 래퍼가 아닙니다. 프로덕션 환경에서 에이전트를 안정적으로 운영하려면 관심사의 명확한 분리 와 교체 가능한 컴포넌트 구조 가 필수입니다. 잘못 설계된 harness는 모델을 교체하거나 툴을 추가할 때마다 전체 코드를 수정해야 하는 상황을 만듭니다.

동일한 모델을 사용해도 컨텍스트 구성, 도구, 검증 루프 같은 harness 변수를 바꾸면 벤치마크 결과가 달라질 수 있습니다. 따라서 아키텍처 결정은 일반적인 향상률을 가정하기보다, 모델과 과제 표본을 고정한 대조 실험으로 검증해야 합니다.

4계층 아키텍처

┌─────────────────────────────────────────────────────┐
│                  Entry & UI Layer                   │
│   TUI / Web UI  │  ConfigManager  │  SessionManager │
│                 │  ApprovalManager                  │
├─────────────────────────────────────────────────────┤
│                 Agent Core Layer                    │
│   MainAgent (parameterized)  │  SubAgentSpec        │
│   AgentDependencies          │  SubAgentDeps        │
├─────────────────────────────────────────────────────┤
│              Tool & Context Layer                   │
│   ToolRegistry  │  PromptComposer  │  MCPClient     │
│   ContextCompactor           │  EventReminder       │
├─────────────────────────────────────────────────────┤
│               Persistence Layer                     │
│   SessionStore  │  ConfigResolver  │  OperationLog  │
│   ProviderCache              │  GitRollback         │
└─────────────────────────────────────────────────────┘

각 계층은 아래 계층에만 의존 하며, 위 계층은 인터페이스를 통해 접근합니다. 이 단방향 의존성이 테스트 용이성과 교체 가능성을 보장합니다.

계층별 책임

| 계층 | 핵심 책임 | 주요 컴포넌트 | |------|-----------|---------------| | Entry & UI | 부트스트랩, 사용자 입출력, 승인 요청 | ConfigManager, SessionManager, ApprovalManager | | Agent Core | 에이전트 생명주기, 서브에이전트 조율 | MainAgent, SubAgentSpec, Dependency Injection | | Tool & Context | 툴 실행, 프롬프트 조합, 컨텍스트 관리 | ToolRegistry, PromptComposer, MCP Client | | Persistence | 상태 저장, 설정 해석, 롤백 | SessionStore, ConfigResolver, OperationLog |

설계 원칙

1. 관심사 분리 (Separation of Concerns)

각 계층은 하나의 책임만 집니다. UI 계층은 렌더링만, Core 계층은 에이전트 로직만 담당합니다. 이 원칙을 어기면 UI가 바뀔 때 에이전트 로직도 함께 수정해야 하는 결합이 발생합니다.

# 나쁜 예: UI 계층에 에이전트 로직 혼재
async function handleUserInput(input: string) {
  renderSpinner()
  const response = await llm.complete(buildPrompt(input))  // ← 잘못된 위치
  renderResponse(response)
}

# 좋은 예: 계층 경계 유지
async function handleUserInput(input: string) {
  renderSpinner()
  const response = await agentCore.run(input)  // ← 위임
  renderResponse(response)
}

2. 의존성 주입 (Dependency Injection)

MainAgent 는 구체적인 구현 대신 인터페이스 를 받습니다. 이를 통해 테스트에서 mock을, 프로덕션에서 실제 구현을 주입할 수 있습니다.

interface AgentDependencies {
  llmClient: LLMClient;
  toolRegistry: ToolRegistry;
  sessionStore: SessionStore;
  promptComposer: PromptComposer;
}

class MainAgent {
  constructor(private deps: AgentDependencies) {}
}

3. 단일 구체 클래스 (Single Concrete Class)

상속 계층 대신 생성 파라미터로 행동을 변화 시킵니다. PlannerAgent, ExecutorAgent 같은 별도 클래스를 만드는 대신, MainAgent 에 SubAgentSpec 을 전달해 역할을 정의합니다.

이 패턴의 장점은 모든 에이전트가 동일한 실행 경로를 공유하므로, 버그 수정이 전체에 즉시 반영된다는 점입니다.

Entry & UI 계층 상세

부트스트랩 시점에 공유 매니저들을 초기화합니다.

// 부트스트랩 진입점
async function bootstrap(config: AppConfig) {
  const configManager = new ConfigManager(config);
  const sessionManager = new SessionManager(configManager);
  const approvalManager = new ApprovalManager(configManager);

  const ui = config.mode === 'tui'
    ? new TUIAdapter(approvalManager)
    : new WebUIAdapter(approvalManager);

  return new Application({ configManager, sessionManager, approvalManager, ui });
}

UICallback 인터페이스를 통해 TUI와 Web UI가 동일한 계약을 구현합니다. Agent Core는 구체적인 UI 타입을 알 필요가 없습니다.

Persistence 계층과 설정 해석

설정은 우선순위 계층 을 통해 해석됩니다.

프로젝트 로컬 (.agent/config.json)
    ↓ 없으면
사용자 글로벌 (~/.config/agent/config.json)
    ↓ 없으면
환경 변수 (AGENT_MODEL, AGENT_TOKEN 등)
    ↓ 없으면
내장 기본값

이 계층적 해석은 로컬 오버라이드를 허용하면서도 글로벌 기본값을 유지하게 해줍니다. CI/CD 환경에서는 환경 변수로, 개발자 로컬에서는 프로젝트 설정으로 제어할 수 있습니다.

기술 선택 기준

아키텍처를 설계할 때 각 계층의 구현 기술을 선택하는 기준이 있습니다. 단순히 인기 있는 기술을 고르는 것이 아니라, 계층의 특성과 요구사항에 맞는 선택이 필요합니다.

계층별 기술 선택 가이드

| 계층 | 고려 기준 | 추천 방향 | |------|-----------|-----------| | Entry & UI | 렌더링 성능, 플랫폼 지원 범위 | TUI는 ink/blessed, Web은 React/Vue | | Agent Core | 타입 안전성, 비동기 처리 | TypeScript + async/await 패턴 | | Tool & Context | 확장성, 플러그인 지원 | 인터페이스 기반 등록 패턴 | | Persistence | 내구성, 조회 성능 | SQLite(로컬), PostgreSQL(팀) |

LLM 클라이언트 선택 기준

LLM 클라이언트는 Agent Core의 핵심 의존성입니다. 다음 기준으로 평가합니다.

1. 스트리밍 지원 여부 — 긴 응답에서 UX에 직접 영향
2. 툴 호출(tool_use) 네이티브 지원 — 파싱 오버헤드 감소
3. 재시도 및 백오프 내장 — 안정성 확보
4. 멀티모달 지원 — 이미지/문서 처리 필요 시
5. 비용 추적 API — 토큰 사용량 모니터링

확장성 고려사항

단일 에이전트 harness가 팀 환경으로 성장할 때 가장 먼저 병목이 되는 지점이 있습니다.

수평 확장 패턴

단일 프로세스 (초기)
  MainAgent ─── ToolRegistry

멀티 워커 (팀 규모)
  LoadBalancer
    ├── Worker 1: MainAgent ─── ToolRegistry (shared)
    ├── Worker 2: MainAgent ─── ToolRegistry (shared)
    └── Worker 3: MainAgent ─── ToolRegistry (shared)
                        ↓
               Persistence Layer (공유 DB)

수평 확장 시 상태를 Persistence 계층에 완전히 위임 해야 합니다. Agent Core가 인메모리 상태를 갖고 있으면 워커 간 세션이 공유되지 않습니다.

툴 레지스트리의 동적 확장

프로덕션에서는 런타임에 툴을 추가하거나 비활성화해야 하는 경우가 생깁니다.

class ToolRegistry {
  private tools = new Map<string, Tool>();

  register(tool: Tool): void {
    this.tools.set(tool.name, tool);
  }

  unregister(name: string): void {
    this.tools.delete(name);
  }

  getAvailableTools(context: AgentContext): Tool[] {
    // 컨텍스트에 따라 사용 가능한 툴 필터링
    return Array.from(this.tools.values())
      .filter(tool => tool.isAvailable(context));
  }
}

이 패턴은 특정 에이전트에게만 특정 툴을 노출하거나, 위험한 툴을 사용자 승인 없이는 실행 불가능하게 만드는 데 사용합니다.

컨텍스트 압축과 메모리 관리

긴 대화가 이어지면 컨텍스트 윈도우가 포화됩니다. Persistence 계층과 Tool & Context 계층이 협력해 이를 해결합니다.

대화 길이가 임계치 초과
    ↓
ContextCompactor 활성화
    ↓
최근 N개 메시지 + 중요 요약 유지
    ↓
나머지는 SessionStore에 아카이브
    ↓
필요 시 검색(retrieve)으로 복원

컨텍스트 압축 전략은 에이전트의 작업 특성에 따라 다릅니다. 코드 작성 에이전트는 최근 파일 변경 이력을, 연구 에이전트는 중간 결론을 우선 유지해야 합니다.

계층 간 통신 패턴

계층 간 데이터 흐름은 이벤트 기반 또는 직접 호출 두 가지 패턴으로 구현할 수 있습니다.

| 패턴 | 장점 | 단점 | 적합한 경우 | |------|------|------|-------------| | 직접 호출 | 단순하고 디버깅 쉬움 | 강한 결합 | 단일 프로세스, 소규모 | | 이벤트 버스 | 느슨한 결합, 확장 용이 | 흐름 추적 어려움 | 멀티 에이전트, 대규모 | | 메시지 큐 | 비동기 처리, 백프레셔 | 운영 복잡도 증가 | 고부하, 분산 환경 |

초기에는 직접 호출로 시작하고, 에이전트 수가 늘어나면 이벤트 버스로 전환하는 것이 일반적인 진화 경로입니다.