AI 에이전트를 위한 컨텍스트 엔지니어링: Manus 개발에서 얻은 교훈
AI 에이전트 개발 프로젝트인 Manus를 진행하면서, 저자와 팀은 중요한 결정을 내려야 했습니다. 바로, 오픈소스 기반의 엔드 투 엔드 에이전트 모델을 직접 학습시킬지, 아니면 최신 대형 언어 모델(LLM)의 인-컨텍스트 러닝(in-context learning) 능력을 활용해 그 위에 에이전트를 구축할지에 대한 선택이었습니다.
과거의 경험과 새로운 선택
과거에는 BERT와 같은 모델을 새로운 작업에 적용하려면 반드시 파인튜닝과 평가 과정을 거쳐야 했습니다. 이 과정은 모델이 지금보다 훨씬 작았음에도 불구하고, 한 번의 반복에 몇 주씩 걸릴 정도로 느렸습니다. 빠른 피드백이 중요한 스타트업 환경에서는 이런 느린 속도가 치명적이었죠. 저자는 이전 스타트업에서 직접 모델을 학습시키며 이런 한계를 뼈저리게 느꼈다고 고백합니다.
"그때는 모델을 직접 학습시키는 수밖에 없었고, 그 느린 피드백 루프가 결국 큰 장애물이 되었다."
하지만 GPT-3와 Flan-T5 같은 모델이 등장하면서 상황이 완전히 바뀌었습니다. 인-컨텍스트 러닝이 가능해지면서, 더 이상 모델을 직접 학습시키지 않아도 다양한 작업에 빠르게 적용할 수 있게 된 것입니다. 이 경험을 바탕으로, Manus는 컨텍스트 엔지니어링에 집중하기로 결정했습니다. 이렇게 하면 몇 주가 아니라 몇 시간 만에 제품을 개선할 수 있고, 모델이 발전해도 제품이 그 흐름을 따라갈 수 있기 때문입니다.
"모델의 발전이 밀물이라면, Manus는 바닥에 고정된 기둥이 아니라 그 위를 떠다니는 배가 되고 싶었다."
컨텍스트 엔지니어링의 현실
하지만 컨텍스트 엔지니어링은 결코 단순하지 않았습니다. 저자와 팀은 네 번이나 에이전트 프레임워크를 완전히 다시 만들었고, 그 과정에서 더 나은 컨텍스트 구성 방법을 찾아냈습니다. 이 과정을 팀에서는 농담 삼아 "Stochastic Graduate Descent"라고 부릅니다. 즉, 시행착오와 실험, 그리고 경험적 추측이 뒤섞인 과정이지만, 실제로 효과가 있었습니다.
이 글에서는 저자와 팀이 직접 겪으며 얻은 최적의 컨텍스트 엔지니어링 원칙들을 공유합니다. AI 에이전트를 개발하는 분들에게 도움이 되길 바라는 마음에서입니다.
1. KV-캐시(KV-Cache)를 중심에 두고 설계하라
KV-캐시 히트율은 실제 서비스 단계의 AI 에이전트에서 가장 중요한 지표라고 저자는 강조합니다. 이 지표는 곧 지연 시간과 비용에 직결되기 때문입니다.
에이전트의 동작 방식
일반적인 에이전트는 다음과 같은 과정을 반복합니다.
- 사용자 입력을 받는다.
- 현재 컨텍스트를 바탕으로 모델이 액션(행동)을 선택한다.
- 선택한 액션을 환경(예: Manus의 가상 머신 샌드박스)에서 실행한다.
- 그 결과(관찰값)를 컨텍스트에 추가한다.
- 이 과정을 반복해 최종 목표를 달성한다.
이 과정에서 컨텍스트는 점점 길어지고, 출력(예: 함수 호출)은 상대적으로 짧게 유지됩니다. Manus의 경우, 입력 대 출력 토큰 비율이 약 100:1에 달합니다.
KV-캐시의 중요성
컨텍스트의 앞부분이 동일하다면, KV-캐시를 활용해 첫 토큰 생성 시간(TTFT)과 추론 비용을 크게 줄일 수 있습니다. 예를 들어, Claude Sonnet 모델에서는 캐시된 입력 토큰은 0.30 USD/MTok, 캐시되지 않은 토큰은 3 USD/MTok로, 무려 10배 차이가 납니다.
KV-캐시 최적화 실천법
- 프롬프트 프리픽스(시스템 프롬프트 등)는 항상 동일하게 유지
- 예를 들어, 초 단위까지 포함된 타임스탬프를 프롬프트에 넣으면 캐시가 무효화됩니다.
- 컨텍스트는 추가만 하고, 이전 내용을 수정하지 않는다
- JSON 직렬화 시 키 순서가 바뀌면 캐시가 깨질 수 있으니, 항상 결정적인(Deterministic) 직렬화를 사용해야 합니다.
- 캐시가 끊기는 지점을 명확히 표시
- 일부 프레임워크에서는 수동으로 캐시 브레이크포인트를 지정해야 하므로, 시스템 프롬프트 끝까지는 반드시 포함해야 합니다.
"심지어 한 글자만 달라도, 그 이후 캐시는 모두 무효가 된다."
- vLLM 등 자체 호스팅 모델을 쓸 때는 프리픽스/프롬프트 캐싱을 꼭 활성화
- 세션 ID 등으로 분산 환경에서도 일관성 있게 요청을 라우팅해야 합니다.
2. 삭제하지 말고 마스킹하라
에이전트가 다룰 수 있는 도구(액션)가 많아질수록, 모델이 잘못된 행동을 하거나 비효율적인 경로를 선택할 가능성이 높아집니다. 최근 MCP(Model Context Protocol) 등으로 인해 도구의 수가 폭발적으로 늘어나고 있습니다.
동적 액션 스페이스의 문제점
- 도구를 동적으로 추가/삭제하면, 컨텍스트 앞부분(시스템 프롬프트 근처)이 바뀌어 KV-캐시가 무효화됩니다.
- 이전 행동/관찰이 더 이상 정의되지 않은 도구를 참조하면, 모델이 혼란스러워집니다.
- 제약된 디코딩(constrained decoding)이 없으면 스키마 오류나 환각(hallucination)이 발생할 수 있습니다.
Manus의 해결책: 마스킹
Manus는 상태 머신을 활용해 도구의 사용 가능 여부를 관리합니다. 도구를 삭제하지 않고, 디코딩 과정에서 토큰 로짓을 마스킹해 특정 액션만 선택할 수 있도록 합니다.
함수 호출 방식의 예시 (Hermes 포맷 기준)
- Auto: 함수 호출 여부를 모델이 자유롭게 결정
- Required: 반드시 함수 호출, 어떤 함수인지는 자유
- Specified: 특정 함수만 호출 가능
이 방식을 활용해, 예를 들어 사용자가 새 입력을 주면 Manus는 즉시 답변만 하도록 하고, 액션은 취하지 않게 할 수 있습니다. 또한, 도구 이름에 일관된 접두사를 붙여(예: browser_, shell_) 상태에 따라 쉽게 그룹별로 선택을 제한할 수 있습니다.
"도구를 삭제하지 않고, 마스킹만으로 액션 선택을 제어하면, 에이전트 루프가 훨씬 안정적으로 동작한다."
3. 파일 시스템을 컨텍스트로 활용하라
최신 LLM은 128K 토큰 이상의 컨텍스트 윈도우를 제공하지만, 실제 에이전트 환경에서는 여전히 부족하거나 오히려 문제가 될 수 있습니다.
현실적인 한계
- 관찰값이 매우 클 수 있음
- 웹페이지, PDF 등 비정형 데이터와 상호작용할 때 컨텍스트 한도를 쉽게 초과합니다.
- 컨텍스트가 길어질수록 모델 성능 저하
- 긴 입력은 비용이 많이 듦
- 프리픽스 캐싱이 있어도, 모든 토큰을 전송하고 채워야 하므로 비용이 발생합니다.
정보 손실 없는 압축 전략
많은 시스템이 컨텍스트를 잘라내거나 압축하지만, 너무 과하면 중요한 정보가 사라집니다. 어떤 관찰값이 나중에 중요해질지 예측할 수 없기 때문입니다.
Manus는 파일 시스템을 무한한, 영구적인 외부 메모리로 활용합니다. 모델이 필요할 때 파일을 읽고 쓰도록 학습시켜, 파일 시스템을 단순 저장소가 아니라 구조화된 외부 기억장치로 사용하는 것이죠.
예를 들어, 웹페이지의 내용은 URL만 남기고 컨텍스트에서 제거할 수 있고, 문서의 경로만 남겨두면 언제든 다시 불러올 수 있습니다. 이렇게 하면 컨텍스트 길이를 줄이면서도 정보 손실을 막을 수 있습니다.
"파일 시스템을 외부 기억장치로 삼으면, 에이전트가 장기 상태를 컨텍스트에 담지 않고도 효율적으로 동작할 수 있다."
4. 리사이테이션(Recitation)으로 주의를 조작하라
Manus를 써본 사람이라면, 복잡한 작업을 할 때 todo.md 파일을 만들고, 진행 상황에 따라 항목을 하나씩 체크해 나가는 모습을 볼 수 있습니다.
이것은 단순한 귀여운 행동이 아니라, 모델의 주의를 조작하는 의도적인 메커니즘입니다.
Manus는 평균적으로 50번 정도의 도구 호출이 필요한 긴 작업을 수행합니다. 이 과정에서 LLM이 목표를 잊거나, 주제가 흐트러질 위험이 있습니다.
todo 리스트를 계속 갱신하며 컨텍스트 끝에 목표를 반복해서 써넣음으로써, 모델의 최근 주의 영역에 전체 계획을 유지시킵니다.
이렇게 하면 "중간에서 잃어버림(lost-in-the-middle)" 현상을 줄이고, 목표와의 불일치를 방지할 수 있습니다.
"자연어로 목표를 반복해 써넣는 것만으로도, 모델의 주의를 원하는 곳에 집중시킬 수 있다."
5. 잘못된 정보도 남겨두라
에이전트는 실수를 합니다. 언어 모델이 환각을 일으키거나, 환경에서 에러가 발생하거나, 외부 도구가 오작동하는 등 다양한 실패가 반복적으로 일어납니다.
많은 개발자들은 이런 오류를 숨기고, 흔적을 지우거나, 상태를 리셋하고 다시 시도하는 경향이 있습니다. 하지만 이렇게 하면 실패의 증거가 사라져, 모델이 학습하거나 적응할 기회를 잃게 됩니다.
Manus에서는 실패한 행동과 그 결과(에러 메시지, 스택 트레이스 등)를 컨텍스트에 그대로 남깁니다. 모델이 이를 보고 내부 신념을 업데이트하게 하여, 비슷한 실수를 반복할 확률을 줄입니다.
"실패를 지우지 않고 남겨두는 것이, 에이전트의 행동을 개선하는 가장 효과적인 방법 중 하나였다."
6. Few-shot에 갇히지 마라
Few-shot 프롬프트는 LLM의 출력을 개선하는 데 자주 쓰이지만, 에이전트 시스템에서는 오히려 부작용이 생길 수 있습니다.
모델은 컨텍스트에 있는 행동-관찰 쌍을 그대로 따라 하려는 경향이 있습니다.
예를 들어, 20개의 이력서를 검토하는 작업에서, 비슷한 행동이 반복되면 모델이 그 패턴에 갇혀 드리프트(편향), 과도한 일반화, 심지어 환각까지 일으킬 수 있습니다.
Manus는 이를 해결하기 위해, 행동과 관찰에 구조적 다양성을 일부러 도입합니다.
- 직렬화 템플릿을 다르게 하거나
- 표현을 바꾸거나
- 순서나 포맷에 약간의 노이즈를 추가하는 식입니다.
"컨텍스트가 너무 균일해지면, 에이전트가 쉽게 깨지기 쉽다. 다양성을 주어야 한다."
결론
컨텍스트 엔지니어링은 아직 발전 중인 분야이지만, 에이전트 시스템에서는 이미 필수적인 기술입니다.
모델이 아무리 강력해져도, 기억, 환경, 피드백을 어떻게 다루느냐가 에이전트의 성능을 좌우합니다.
Manus 팀은 수많은 시행착오와 실제 사용자 테스트를 거치며 이 원칙들을 얻었습니다.
이 글의 내용이 보편적 진리는 아니지만, 여러분이 비슷한 시행착오를 줄이는 데 도움이 되길 바랍니다.
"에이전트의 미래는, 한 번에 하나의 컨텍스트로 만들어진다. 잘 설계하라."
핵심 키워드:
- KV-캐시
- 컨텍스트 엔지니어링
- 도구 마스킹
- 파일 시스템 외부 메모리
- 리사이테이션(Recitation)
- 실패 기록
- 다양성(anti-few-shot)
- 에이전트 시스템
- LLM
- Manus
이상으로, AI 에이전트 개발에서 컨텍스트 엔지니어링의 실제 원칙과 교훈을 시간순으로 정리해보았습니다.
궁금한 점이 있다면 언제든 질문해 주세요! 😊