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