AI 에이전트를 위한 컨텍스트 엔지니어링: Manus 구축에서 얻은 실전 교훈

⏱️ 예상 읽기 시간: 12분

서론

AI 에이전트 개발에서 가장 어려운 선택 중 하나는 모델 훈련과 컨텍스트 엔지니어링 사이의 결정입니다. Manus AI팀의 Yichao ‘Peak’ Ji가 공유한 실전 경험을 통해, 프로덕션 환경에서 검증된 컨텍스트 엔지니어링 전략을 살펴보겠습니다.

BERT 시대부터 GPT-3까지의 변화를 경험한 Manus팀은 “확률적 대학원생 하강법(Stochastic Graduate Descent)”이라고 불리는 경험적 접근법을 통해 4번의 프레임워크 재구축을 거쳐 현재의 최적화 전략에 도달했습니다.

KV-캐시 중심 설계: 프로덕션 에이전트의 핵심 지표

왜 KV-캐시 히트율이 중요한가?

프로덕션 단계 AI 에이전트에서 KV-캐시 히트율은 가장 중요한 성능 지표입니다. 이는 지연 시간과 비용에 직접적인 영향을 미치기 때문입니다.

일반적인 에이전트 작업 플로우:

1. 사용자 입력 수신
2. 현재 컨텍스트 기반 액션 선택
3. 환경에서 액션 실행 및 관찰 생성
4. 컨텍스트에 액션-관찰 쌍 추가
5. 작업 완료까지 반복

Manus의 실제 데이터: 평균 입력 대 출력 토큰 비율이 100:1

비용 최적화의 실제 임팩트

Claude Sonnet 기준 비용 비교:

• 캐시된 입력 토큰: 0.30 USD/MTok
• 캐시되지 않은 토큰: 3.00 USD/MTok
• 10배 비용 차이 발생

KV-캐시 최적화 전략

1. 프롬프트 접두사 안정화

# ❌ 캐시 무효화하는 패턴
system_prompt = f"""
현재 시간: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
당신은 AI 에이전트입니다...
"""

# ✅ 캐시 친화적 패턴
system_prompt = """
당신은 AI 에이전트입니다...
현재 작업: {task_description}
"""

2. 추가 전용 컨텍스트 설계

class AgentContext:
    def __init__(self):
        self.actions = []
        self.observations = []
    
    def add_step(self, action, observation):
        # ✅ 추가만 수행, 수정 없음
        self.actions.append(action)
        self.observations.append(observation)
    
    def serialize(self):
        # ✅ 결정적 직렬화 보장
        return json.dumps({
            'actions': self.actions,
            'observations': self.observations
        }, sort_keys=True)

3. 캐시 중단점 명시적 관리

def create_cache_breakpoints(context):
    breakpoints = [
        'system_prompt_end',
        'tools_definition_end',
        'conversation_start'
    ]
    
    for bp in breakpoints:
        context.add_cache_marker(bp)

동적 도구 관리: 마스킹 vs 제거

도구 폭발 문제

MCP(Model Context Protocol) 도입으로 도구 수가 기하급수적으로 증가하는 상황에서, 무분별한 도구 추가는 에이전트의 의사결정 품질을 저하시킵니다.

Manus의 해결책: 컨텍스트 인식 상태 머신

도구를 제거하지 않고 마스킹하는 이유:

1. KV-캐시 보존: 도구 정의가 컨텍스트 앞부분에 위치하므로 변경 시 전체 캐시 무효화
2. 참조 무결성: 이전 액션이 참조하는 도구가 사라지면 모델 혼란 야기

함수 호출 제어 구현

class FunctionCallController:
    def __init__(self):
        self.call_modes = {
            'auto': '<|im_start|>assistant',
            'required': '<|im_start|>assistant<tool_call>',
            'specified': '<|im_start|>assistant<tool_call>{"name": "browser_'
        }
    
    def constrain_tools(self, context, allowed_prefixes):
        """특정 접두사를 가진 도구만 허용"""
        # 토큰 로짓 마스킹을 통한 제어
        pass

도구 명명 규칙

# ✅ 일관된 접두사 사용
BROWSER_TOOLS = [
    'browser_navigate',
    'browser_click',
    'browser_extract'
]

SHELL_TOOLS = [
    'shell_execute',
    'shell_cd',
    'shell_env'
]

파일 시스템을 컨텍스트로 활용

컨텍스트 윈도우의 한계

현대 LLM의 128K+ 토큰 윈도우에도 불구하고 실제 에이전트 시나리오에서 직면하는 문제들:

1. 거대한 관찰 데이터: 웹 페이지, PDF 등 비구조화된 데이터
2. 성능 저하: 긴 컨텍스트에서의 모델 성능 감소
3. 높은 비용: 접두사 캐싱을 사용해도 여전히 비싼 토큰 비용

Manus의 파일 시스템 접근법

class FileSystemContext:
    def __init__(self, sandbox_path):
        self.sandbox_path = sandbox_path
        self.context_files = {}
    
    def store_observation(self, content, context_type):
        """대용량 관찰을 파일로 저장"""
        file_path = f"{self.sandbox_path}/observations/{uuid4()}.{context_type}"
        with open(file_path, 'w') as f:
            f.write(content)
        
        return {
            'type': 'file_reference',
            'path': file_path,
            'summary': self.generate_summary(content)
        }
    
    def restore_observation(self, file_ref):
        """필요시 파일에서 내용 복원"""
        with open(file_ref['path'], 'r') as f:
            return f.read()

복원 가능한 압축 전략

def compress_context(self, context):
    """정보 손실 없는 압축"""
    compressed = []
    
    for item in context:
        if item['type'] == 'web_page':
            # URL 보존하여 복원 가능
            compressed.append({
                'type': 'web_page_ref',
                'url': item['url'],
                'summary': item['summary']
            })
        elif item['type'] == 'document':
            # 파일 경로 보존
            compressed.append({
                'type': 'document_ref',
                'path': item['path'],
                'key_points': item['key_points']
            })
    
    return compressed

어텐션 조작을 통한 목표 유지

할 일 목록 기반 어텐션 제어

Manus가 복잡한 작업에서 todo.md 파일을 생성하고 업데이트하는 이유:

1. 목표 재확인: 컨텍스트 끝에 목표를 반복적으로 배치
2. Lost-in-the-middle 문제 해결: 긴 컨텍스트에서 중요 정보 망각 방지
3. 자연어 기반 어텐션 편향: 특별한 아키텍처 변경 없이 구현

구체적 구현 예시

# todo.md 예시

## 현재 작업: 웹사이트 성능 최적화

### 완료된 작업
- [x] 현재 페이지 로딩 시간 측정
- [x] 이미지 파일 크기 분석
- [x] CSS/JS 파일 압축 상태 확인

### 진행 중인 작업
- [ ] 캐싱 전략 구현
- [ ] 이미지 최적화 적용

### 다음 단계
- [ ] 성능 테스트 실행
- [ ] 결과 보고서 작성

평균 작업 복잡도

Manus 실제 데이터: 일반적인 작업당 평균 50개의 도구 호출 필요

오류 활용 전략: 실패를 숨기지 말고 학습하기

실패 제거의 함정

일반적인 오류 처리 접근법:

• 실패한 액션 제거
• 상태 리셋 및 재시도
• “Temperature” 조정을 통한 무작위성 추가

Manus의 오류 활용 전략

class ErrorLearningContext:
    def handle_failed_action(self, action, error):
        """실패한 액션을 컨텍스트에 유지"""
        error_context = {
            'action': action,
            'error': error,
            'timestamp': datetime.now(),
            'learning_signal': True
        }
        
        # ✅ 실패 정보를 컨텍스트에 유지
        self.context.append(error_context)
        
        # 모델이 유사한 실수를 반복할 확률 감소
        self.update_action_priors(action, negative_signal=True)

오류 복구의 중요성

오류 복구는 진정한 에이전트적 행동의 핵심 지표입니다. 현재 대부분의 학술 연구와 벤치마크가 이상적 조건에서의 성공에만 초점을 맞추고 있어, 실제 프로덕션 환경의 복잡성을 반영하지 못하고 있습니다.

퓨샷 프롬프팅의 함정 피하기

패턴 모방의 위험성

언어 모델의 뛰어난 모방 능력이 에이전트 시스템에서는 오히려 문제가 될 수 있습니다:

# ❌ 문제가 되는 균일한 패턴
context_examples = [
    "액션: 파일 분석, 관찰: 20개 항목 발견",
    "액션: 파일 분석, 관찰: 15개 항목 발견",
    "액션: 파일 분석, 관찰: 25개 항목 발견"
]
# 모델이 항상 "파일 분석"만 선택하게 됨

Manus의 다양성 증진 전략

class ContextDiversifier:
    def add_structural_variation(self, action, observation):
        """구조적 변화 도입"""
        templates = [
            "실행: {action} → 결과: {observation}",
            "액션: {action}\n관찰: {observation}",
            "{action} 수행 완료. {observation}"
        ]
        
        template = random.choice(templates)
        return template.format(action=action, observation=observation)
    
    def add_semantic_noise(self, text):
        """의미 보존하면서 표현 다양화"""
        synonyms = {
            '분석': ['검토', '조사', '확인'],
            '실행': ['수행', '진행', '처리']
        }
        # 동의어 무작위 치환
        return self.apply_synonyms(text, synonyms)

실전 적용 가이드

개발 단계별 체크리스트

1. 설계 단계

• KV-캐시 친화적 프롬프트 구조 설계
• 도구 명명 규칙 정의 (일관된 접두사)
• 파일 시스템 기반 메모리 아키텍처 계획

2. 구현 단계

• 추가 전용 컨텍스트 구조 구현
• 토큰 로짓 마스킹 기반 도구 제어
• 복원 가능한 압축 전략 구현

3. 최적화 단계

• KV-캐시 히트율 모니터링
• 컨텍스트 다양성 메커니즘 도입
• 오류 학습 시스템 구축

성능 모니터링 메트릭

class AgentMetrics:
    def __init__(self):
        self.metrics = {
            'kv_cache_hit_rate': 0.0,
            'avg_context_length': 0,
            'error_recovery_rate': 0.0,
            'task_completion_rate': 0.0,
            'cost_per_interaction': 0.0
        }
    
    def calculate_efficiency_score(self):
        """종합 효율성 점수 계산"""
        weights = {
            'kv_cache_hit_rate': 0.3,
            'error_recovery_rate': 0.25,
            'task_completion_rate': 0.25,
            'cost_efficiency': 0.2
        }
        
        return sum(self.metrics[k] * weights[k] for k in weights)

미래 전망: 상태 공간 모델과 에이전트

SSM의 가능성

Manus팀이 제시한 흥미로운 관점: 상태 공간 모델(SSM)이 파일 기반 메모리를 마스터한다면, Transformer의 완전한 어텐션 없이도 효율적인 에이전트를 구현할 수 있을 것입니다.

SSM 기반 에이전트의 잠재적 장점:

• 속도: Transformer 대비 빠른 추론
• 효율성: 메모리 사용량 최적화
• 확장성: 긴 시퀀스 처리 능력

이는 Neural Turing Machine의 진정한 후계자가 될 수 있는 가능성을 제시합니다.

결론

Manus팀의 4번의 프레임워크 재구축을 통해 얻은 교훈은 명확합니다: 컨텍스트 엔지니어링은 AI 에이전트 개발의 핵심이며, 체계적인 접근이 필요합니다.

핵심 원칙 요약

1. KV-캐시 최우선: 히트율 최적화가 성능과 비용에 직결
2. 마스킹 > 제거: 도구 관리에서 안정성 확보
3. 파일 시스템 활용: 무제한 컨텍스트를 위한 외부 메모리
4. 실패 학습: 오류를 숨기지 말고 학습 신호로 활용
5. 다양성 유지: 패턴 함정을 피하는 구조적 변화

실무진을 위한 조언

AI 에이전트 개발팀이라면 다음 질문을 통해 현재 시스템을 점검해보세요:

• KV-캐시 히트율을 측정하고 있나요?
• 도구 추가 시 전체 캐시가 무효화되나요?
• 실패한 액션을 어떻게 처리하고 있나요?
• 컨텍스트가 너무 균일하지는 않나요?

컨텍스트 엔지니어링은 여전히 발전하는 분야입니다. 하지만 Manus와 같은 실제 프로덕션 환경에서 검증된 원칙들을 바탕으로, 더 효율적이고 안정적인 AI 에이전트를 구축할 수 있습니다.

에이전트의 미래는 정교하게 설계된 컨텍스트 위에 구축될 것입니다. 지금부터 시작하세요.

---

참고 자료:

• Manus AI 원문 블로그
• KV-Cache 최적화 관련 연구
• MCP (Model Context Protocol) 문서