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