로컬 LLM에서 자율 에이전트로: 범위 내에 머무는 AI 기반 개발 도구 구축하기

Originally published on tamiz.pro.

LLM으로 구동되는 모든 개발 도구는 결국 같은 벽에 부딪힙니다: 모델이 요청하지 않은 행동을 하는 것입니다. 수정해서는 안 되는 파일을 재작성하거나, 레지스트리에 존재하지 않는 API를 호출하거나, 무한히 자기 수정을 반복하는 서브 에이전트를 생성합니다. 코드를 제안하는 챗봇과 그것을 _실행_하는 자율 에이전트 사이의 간극은 모델 지능의 문제가 아니라 아키텍처적 규율의 문제입니다.

본 글에서는 로컬 LLM 에이전트가 경계 지어지고(bounded), 예측 가능하며, 실제 개발 도구에서 유용하게 유지되도록 하는 엔지니어링 패턴들을 분석합니다. 우리는 에이전트를 블랙박스가 아닌 시스템 구성 요소로 취급하며, 모델 선택부터 오케스트레이션, 가드레일 강제 적용, 툴 사용 프로토콜, 그리고 프로덕션 배포에 이르기까지 전 과정을 다룰 것입니다.

목차

• 1. 범위 확장 문제 (The Scope Creep Problem)
• 2. 모델 선택: 로컬 모델이 방정식을 바꾸는 이유
• 3. 아키텍처: 경계 지어진 에이전트 패턴 (The Bounded Agent Pattern)
• 4. 툴 레지스트리 및 기능 범위 지정
• 5. 가드레일 강제 적용 계층
• 6. 구조화된 출력 및 스키마 바인딩
• 7. 실행 샌드박싱
• 8. 관측 가능성 및 감사 추적 (Observability and Audit Trails)
• 9. 프로덕션 배포 패턴
• 10. 자주 묻는 질문

근본적인 원인은 아키텍처에 있습니다: 대부분의 에이전트 프레임워크는 LLM을 제한 없는 도구 네임스페이스(flat tool namespace)에 접근하는 오케스트레이터로 취급합니다. 모델은 무엇을 호출할지, 어떻게 호출할지, 그리고 몇 번이나 호출할지를 결정합니다.

핵심 설계 결정 사항: LLM은 도구에 직접 접근할 수 없습니다. 대신 구조화된 제안을 출력하며, 이는 별도의 런타임(runtime)에서 검증되고, 승인되며, 실행됩니다.

4. 도구 레지스트리 및 기능 범위 지정 (Tool Registry and Capability Scoping)

도구 레지스트리는 단순한 함수 매핑이 아닙니다. 각 도구가 무엇을 할 수 있는지, 무엇을 필요로 하는지, 그리고 어떤 제약 조건이 적용되는지를 정의하는 기능 선언 시스템입니다.

// tool-registry.ts
import { z } from 'zod';

...

에이전트 프로필: 도구 세트 구성 (Agent Profiles: Composing Tool Sets)

서로 다른 에이전트 역할은 서로 다른 도구 하위 집합을 받습니다:

// agent-profiles.ts

export const CODE_REVIEWER: AgentProfile = {
...

5. 가드레일 강제 적용 계층 (Guardrail Enforcement Layers)

가드레일은 여러 계층에서 작동합니다. 모델이 단일 계층에 의해 속임당할 수는 있지만, 복합 시스템 전체는 견고합니다.

계층 1: 입력 필터링 (프롬프트 수준) (Layer 1: Input Filtering (Prompt-Level))

사용자 요청이 LLM에 도달하기 전에 주입 패턴(injection patterns)을 필터링합니다:

// input-filter.ts

const INJECTION_PATTERNS = [
...

계층 2: 출력 검증 (스키마 강제 적용) (Layer 2: Output Validation (Schema Enforcement))

LLM의 출력은 엄격한 스키마를 준수해야 합니다. 유효하지 않은 출력은 해석되지 않고 거부됩니다:

// output-validator.ts
import { z } from 'zod';

...

{% endraw %}(?:json)?\n?/m', '').replace(/\n?`

    parsed = JSON.parse(jsonStr);
  } catch {
    return { error: 'INVALID_JSON', raw: raw.slice(0, 200) };
...

계층 3: 정책 엔진 (OPA/Rego) (Layer 3: Policy Engine (OPA/Rego))

복잡한 권한 부여 로직의 경우 Open Policy Agent와 Rego를 사용합니다:

# agent-policy.rego
package agent.policy
...

계층 4: 런타임 강제 적용 (Layer 4: Runtime Enforcement)

정책 승인 후에도 실행 계층은 제약 조건을 강제합니다:

// execution-sandbox.ts
import { spawn } from 'child_process';
import { realpath, stat } from 'fs/promises';
...

6. 구조화된 출력 및 스키마 바인딩 (Structured Output and Schema Binding)

네이티브 함수 호출 기능이 없는 로컬 모델은 명시적인 스키마 바인딩(schema binding)이 필요합니다. 가장 신뢰할 수 있는 접근 방식은 제약 디코딩(constrained decoding)과 검증을 결합하는 것입니다:

// constrained-decoding.ts

// vLLM의 가이드 디코딩을 사용하여 엄격한 JSON 출력 구현
...

모델이 가이드 디코딩을 지원하지 않는 경우, 스키마 유효성 검사를 사용한 재시도 루프를 사용하세요:

// schema-retry.ts

export async function generateWithRetry(
...

7. 실행 샌드박싱 (Execution Sandboxing)

코드를 실행하거나 파일 시스템을 수정하는 도구의 경우, 샌드박싱은 필수적입니다. 접근 방식은 배포 대상에 따라 달라집니다:

Docker 기반 샌드박싱

# Dockerfile.sandbox
FROM node:20-alpine
...

# 엄격한 제약 조건으로 샌드박스 실행
# docker run --rm \
#   --network=none \
...

Web Worker를 사용한 인프로세스 샌드박싱 (In-Process Sandboxing)

전체 컨테이너 격리가 필요하지 않은 낮은 지연 시간(low-latency) 시나리오의 경우:

// worker-sandbox.ts
// 제한된 기능으로 Web Worker에서 실행됨

import { parentPort, workerData } from 'worker_threads';

interface WorkerConfig {
  workspaceRoot: string;
  allowedPaths: string[];
  maxMemoryBytes: number;
  timeoutMs: number;
}