AI 에이전트를 위한 컨텍스트 엔지니어링: Manus 구축에서 얻은 교훈
토요일, 7월 19
기술
2025/7/18 --Yichao 'Peak' Ji
Manus 프로젝트의 시작 단계에서, 저와 제 팀은 중요한 결정에 직면했습니다: 오픈소스 기반 모델을 사용하여 엔드투엔드 에이전트 모델을 훈련시켜야 할까요, 아니면 최첨단 모델의 문맥 내 학습 능력을 기반으로 에이전트를 구축해야 할까요?
NLP 분야에서의 첫 10년 동안, 우리는 그런 선택의 여유가 없었습니다. BERT의 시대(그래요, 벌써 7년이 지났습니다)에는 모델이 새로운 작업에 전이되기 전에 파인튜닝과 평가를 거쳐야만 했습니다. 그 과정은 오늘날의 LLM들에 비해 모델이 작았음에도 불구하고 반복당 몇 주가 걸렸습니다. 빠르게 변화하는 애플리케이션, 특히 PMF 이전 단계에서는 이러한 느린 피드백 루프 가 결정적인 단점이었습니다. 이것은 제 이전 스타트업에서 얻은 쓰라린 교훈이었는데, 당시 저는 오픈 정보 추출과 시맨틱 검색을 위한 모델을 처음부터 훈련시켰습니다. 그러다가 GPT-3와 Flan-T5가 등장했고, 제 자체 모델들은 하룻밤 사이에 무의미해졌습니다. 아이러니하게도, 바로 그 모델들이 문맥 내 학습의 시작점이 되었고 완전히 새로운 앞길을 열었습니다.
그 고생스럽게 얻은 교훈으로 선택이 명확해졌습니다: Manus는 컨텍스트 엔지니어링에 베팅할 것입니다. 이를 통해 몇 주가 아닌 몇 시간 내에 개선 사항을 배포할 수 있으며, 우리 제품이 기반 모델과 직교하도록 유지했습니다: 만약 모델의 발전이 밀물이라면, Manus는 바닷바닥에 고정된 기둥이 아닌 배가 되길 원합니다.
그럼에도 불구하고, 컨텍스트 엔지니어링은 결코 간단하지 않았습니다. 이것은 실험적인 과학이며—우리는 더 나은 컨텍스트 구성 방법을 발견할 때마다 에이전트 프레임워크를 네 번이나 재구축했습니다. 우리는 아키텍처 검색, 프롬프트 조정, 경험적 추측의 이 수동 프로세스를 애정을 담아 "확률적 대학원생 하강법"이라고 부릅니다. 우아하지는 않지만, 효과는 있습니다.
이 글에서는 우리 자신의 "SGD"를 통해 도달한 지역 최적점을 공유합니다. 자신만의 AI 에이전트를 구축하고 있다면, 이 원칙들이 더 빠른 수렴에 도움이 되길 바랍니다.
KV-캐시를 중심으로 설계하기
만약 내가 딱 하나의 지표만 선택해야 한다면, KV-cache 히트율이 프로덕션 단계 AI 에이전트에서 가장 중요한 지표라고 주장하겠습니다. 이는 지연 시간과 비용 모두에 직접적인 영향을 미칩니다. 그 이유를 이해하기 위해, 일반적인 에이전트가 어떻게 작동하는지 살펴보겠습니다:
사용자 입력을 받은 후, 에이전트는 작업을 완료하기 위해 일련의 도구 사용 체인을 진행합니다. 각 반복에서 모델은 현재 컨텍스트를 기반으로 미리 정의된 액션 공간에서 액션을 선택합니다. 그 액션은 환경(예: Manus의 가상 머신 샌드박스)에서 실행되어 관찰을 생성합니다. 액션과 관찰은 컨텍스트에 추가되어 다음 반복을 위한 입력을 형성합니다. 이 루프는 작업이 완료될 때까지 계속됩니다.
아시다시피, 컨텍스트는 모든 단계에서 증가하는 반면, 출력—일반적으로 구조화된 함수 호출—은 상대적으로 짧게 유지됩니다. 이로 인해 에이전트에서는 챗봇과 비교했을 때 프리필링과 디코딩 간의 비율이 크게 치우치게 됩니다. 예를 들어 Manus에서는 평균 입력 대 출력 토큰 비율이 약 100:1입니다.
다행히도, 동일한 접두사를 가진 컨텍스트는 KV-cache를 활용할 수 있으며, 이는 **첫 번째 토큰까지의 시간(TTFT)**과 추론 비용을 크게 줄여줍니다—자체 호스팅 모델을 사용하든 추론 API를 호출하든 상관없이. 그리고 우리가 이야기하는 것은 작은 절약이 아닙니다: 예를 들어 Claude Sonnet에서는 캐시된 입력 토큰 비용이 0.30 USD/MTok인 반면, 캐시되지 않은 토큰은 3 USD/MTok—10배 차이가 납니다.
1.프롬프트 접두사를 안정적으로 유지하세요. LLM의 자기회귀적 특성으로 인해, 단 하나의 토큰 차이만으로도 해당 토큰 이후의 캐시가 무효화될 수 있습니다. 흔한 실수는 시스템 프롬프트 시작 부분에 타임스탬프(특히 초 단위로 정확한)를 포함하는 것입니다. 모델이 현재 시간을 알려줄 수 있게 하지만, 캐시 히트율을 크게 저하시킵니다.
2.컨텍스트를 추가 전용으로 만드세요. 이전 작업이나 관찰을 수정하지 마세요. 직렬화가 결정적이도록 하세요. 많은 프로그래밍 언어와 라이브러리는 JSON 객체를 직렬화할 때 안정적인 키 순서를 보장하지 않으며, 이로 인해 캐시가 조용히 손상될 수 있습니다.
3.필요할 때 캐시 중단점을 명시적으로 표시하세요. 일부 모델 제공업체나 추론 프레임워크는 자동 증분 접두사 캐싱을 지원하지 않고, 대신 컨텍스트에 수동으로 캐시 중단점을 삽입해야 합니다. 이를 할당할 때는 잠재적인 캐시 만료를 고려하고, 최소한 중단점이 시스템 프롬프트의 끝을 포함하도록 하세요.
또한, vLLM과 같은 프레임워크를 사용하여 모델을 자체 호스팅하는 경우, 접두사/프롬프트 캐싱이 활성화되어 있는지 확인하고, 세션 ID와 같은 기술을 사용하여 분산 작업자 간에 요청을 일관되게 라우팅하세요.
마스킹하되, 제거하지 마세요
에이전트가 더 많은 기능을 갖추게 되면 자연스럽게 행동 공간이 더 복잡해집니다—간단히 말해서, 도구의 수가 폭발적으로 증가합니다. 최근 인기 있는 MCP는 이 상황에 불을 지피는 역할만 합니다. 사용자 구성 가능한 도구를 허용한다면, 믿으세요: 누군가는 결국 당신이 신중하게 큐레이션한 행동 공간에 수백 개의 미스터리한 도구를 연결할 것입니다. 결과적으로, 모델이 잘못된 행동을 선택하거나 비효율적인 경로를 취할 가능성이 높아집니다. 간단히 말해, 무장한 에이전트가 더 멍청해집니다.
자연스러운 반응은 동적 행동 공간을 설계하는 것입니다—아마도 RAG와 같은 것을 사용하여 필요에 따라 도구를 로드하는 방식으로요. 우리도 Manus에서 그것을 시도했습니다. 하지만 우리의 실험은 명확한 규칙을 제시합니다: 절대적으로 필요한 경우가 아니라면, 반복 중간에 도구를 동적으로 추가하거나 제거하는 것을 피하세요. 이에는 두 가지 주요 이유가 있습니다:
1.대부분의 LLM에서 도구 정의는 직렬화 후 컨텍스트 앞부분, 일반적으로 시스템 프롬프트 전이나 후에 위치합니다. 따라서 어떤 변경이라도 모든 후속 작업 및 관찰에 대한 KV-캐시를 무효화합니다.
2.이전 작업 및 관찰이 현재 컨텍스트에 더 이상 정의되지 않은 도구를 참조할 때, 모델은 혼란스러워집니다. 제약 디코딩 없이는 이것이 종종 스키마 위반이나 환각된 작업으로 이어집니다.
이 문제를 해결하면서도 작업 선택을 개선하기 위해, Manus는 도구 가용성을 관리하기 위한 컨텍스트 인식 상태 머신을 사용합니다. 도구를 제거하는 대신, 현재 컨텍스트에 기반하여 특정 작업의 선택을 방지(또는 강제)하기 위해 디코딩 중에 토큰 로짓을 마스킹합니다.
•자동 – 모델이 함수를 호출할지 여부를 선택할 수 있습니다. 응답 접두사만 프리필링하여 구현됩니다: <|im_start|>assistant
•필수 – 모델이 반드시 함수를 호출해야 하지만, 선택은 제한되지 않습니다. 도구 호출 토큰까지 프리필링하여 구현됩니다: <|im_start|>assistant<tool_call>
•지정 – 모델이 특정 하위 집합에서 함수를 호출해야 합니다. 함수 이름의 시작 부분까지 프리필링하여 구현됩니다: <|im_start|>assistant<tool_call>{"name": "browser_
이를 통해 토큰 로짓을 직접 마스킹하여 액션 선택을 제한합니다. 예를 들어, 사용자가 새 입력을 제공할 때 Manus는 액션을 취하는 대신 즉시 응답해야 합니다. 또한 액션 이름에 일관된 접두사를 의도적으로 설계했습니다—예를 들어, 모든 브라우저 관련 도구는 browser_로 시작하고, 명령줄 도구는 shell_로 시작합니다. 이를 통해 상태 기반 로짓 프로세서를 사용하지 않고도 특정 상태에서 에이전트가 특정 그룹의 도구만 선택하도록 쉽게 강제할 수 있습니다.
이러한 설계는 모델 기반 아키텍처에서도 Manus 에이전트 루프가 안정적으로 유지되도록 돕습니다.
파일 시스템을 컨텍스트로 사용하기
최신 프론티어 LLM은 이제 128K 토큰 이상의 컨텍스트 윈도우를 제공합니다. 하지만 실제 에이전트 시나리오에서는 이것만으로 충분하지 않으며, 때로는 오히려 부담이 될 수 있습니다. 다음과 같은 세 가지 일반적인 문제점이 있습니다:
1.관찰은 엄청나게 클 수 있으며, 특히 에이전트가 웹 페이지나 PDF와 같은 비구조화된 데이터와 상호작용할 때 그렇습니다. 컨텍스트 제한을 쉽게 초과할 수 있습니다.
2.모델 성능은 특정 컨텍스트 길이를 넘어서면 저하되는 경향이 있습니다, 기술적으로 윈도우가 지원하더라도 말입니다.
3.긴 입력은 비용이 많이 듭니다, 접두사 캐싱을 사용하더라도 말입니다. 여전히 모든 토큰을 전송하고 미리 채우는 비용을 지불해야 합니다.
이를 처리하기 위해, 많은 에이전트 시스템은 컨텍스트 잘라내기나 압축 전략을 구현합니다. 그러나 지나치게 공격적인 압축은 불가피하게 정보 손실로 이어집니다. 문제는 근본적입니다: 에이전트는 본질적으로 모든 이전 상태를 기반으로 다음 행동을 예측해야 합니다—그리고 어떤 관찰이 10단계 후에 중요해질지 확실하게 예측할 수 없습니다. 논리적 관점에서, 모든 비가역적 압축은 위험을 수반합니다.
이것이 바로 Manus에서 우리가 파일 시스템을 최종적인 컨텍스트로 취급하는 이유입니다: 크기 제한이 없고, 본질적으로 영속적이며, 에이전트가 직접 조작할 수 있습니다. 모델은 필요에 따라 파일에 쓰고 읽는 법을 학습하며—파일 시스템을 단순한 저장소가 아닌 구조화된 외부 메모리로 활용합니다.
우리의 압축 전략은 항상 복원 가능하도록 설계되어 있습니다. 예를 들어, URL이 보존되는 한 웹 페이지의 내용은 컨텍스트에서 제외될 수 있으며, 문서의 경로가 샌드박스에서 사용 가능하다면 그 내용은 생략될 수 있습니다. 이를 통해 Manus는 정보를 영구적으로 잃지 않으면서도 컨텍스트 길이를 줄일 수 있습니다.
이 기능을 개발하면서, **상태 공간 모델(State Space Model, SSM)**이 에이전트 환경에서 효과적으로 작동하려면 어떤 조건이 필요할지 상상해보았습니다. 트랜스포머와 달리, SSM은 완전한 어텐션이 없고 장거리 역방향 의존성에 어려움을 겪습니다. 하지만 만약 파일 기반 메모리—컨텍스트 내에 상태를 유지하는 대신 장기 상태를 외부화하는—를 마스터할 수 있다면, 그들의 속도와 효율성이 새로운 종류의 에이전트를 열 수 있을 것입니다. 에이전트 SSM은 신경 튜링 머신의 진정한 후계자가 될 수 있습니다.
낭송을 통한 어텐션 조작
Manus를 사용해 본 적이 있다면, 아마 흥미로운 점을 발견했을 것입니다: 복잡한 작업을 처리할 때, 그것은 todo.md 파일을 생성하고—작업이 진행됨에 따라 단계별로 업데이트하며, 완료된 항목을 체크오프합니다.
이것은 단순히 귀여운 행동이 아닙니다—그것은 어텐션을 조작하기 위한 의도적인 메커니즘입니다.
Manus의 일반적인 작업은 평균적으로 약 50개의 도구 호출이 필요합니다. 이는 긴 루프이며, Manus는 의사 결정을 위해 LLM에 의존하기 때문에 특히 긴 컨텍스트나 복잡한 작업에서 주제에서 벗어나거나 이전 목표를 잊어버리기 쉽습니다.
할 일 목록을 지속적으로 다시 작성함으로써, Manus는 컨텍스트의 끝에 자신의 목표를 암송하고 있습니다. 이는 전체 계획을 모델의 최근 주의 범위로 밀어넣어 "중간에서 길을 잃는" 문제를 피하고 목표 불일치를 줄입니다. 실질적으로, 특별한 아키텍처 변경 없이 자연어를 사용하여 자신의 초점을 작업 목표로 편향시키고 있습니다.
잘못된 것도 유지하세요
에이전트는 실수를 합니다. 그것은 버그가 아니라 현실입니다. 언어 모델은 환각을 일으키고, 환경은 오류를 반환하며, 외부 도구는 오작동하고, 예상치 못한 예외 상황은 항상 발생합니다. 다단계 작업에서 실패는 예외가 아닙니다. 그것은 루프의 일부입니다.
그럼에도 불구하고, 일반적인 충동은 이러한 오류를 숨기는 것입니다: 추적 내용을 정리하거나, 작업을 다시 시도하거나, 모델의 상태를 재설정하고 마법같은 "temperature"에 맡기는 것입니다. 그것이 더 안전하고 통제된 것처럼 느껴집니다. 하지만 그것은 대가가 따릅니다: 실패를 지우면 증거가 제거됩니다. 그리고 증거 없이는 모델이 적응할 수 없습니다.
퓨샷에 속지 마세요
퓨샷 프롬프팅은 LLM 출력을 개선하기 위한 일반적인 기술입니다. 하지만 에이전트 시스템에서는 미묘한 방식으로 역효과를 낼 수 있습니다.
언어 모델은 뛰어난 모방자입니다; 그들은 맥락 속에서 행동 패턴을 모방합니다. 맥락이 유사한 과거 행동-관찰 쌍으로 가득 차 있다면, 모델은 더 이상 최적이 아닐 때도 그 패턴을 따르는 경향이 있습니다.
이는 반복적인 결정이나 행동을 포함하는 작업에서 위험할 수 있습니다. 예를 들어, Manus를 사용하여 20개의 이력서를 검토할 때, 에이전트는 종종 리듬에 빠지게 됩니다—단순히 맥락에서 보이는 것이기 때문에 유사한 행동을 반복합니다. 이로 인해 표류, 과도한 일반화 또는 때로는 환각이 발생합니다.
해결책은 다양성을 증가시키는 것입니다. Manus는 행동과 관찰에 작은 양의 구조화된 변화를 도입합니다—다른 직렬화 템플릿, 대체 문구, 순서나 형식의 작은 노이즈 등. 이러한 제어된 무작위성은 패턴을 깨고 모델의 주의력을 조정하는 데 도움이 됩니다.
다시 말해, 자신을 몇 가지 예시에 갇히게 하지 마세요. 맥락이 균일할수록 에이전트는 더 취약해집니다.
결론
맥락 공학은 아직 새롭게 부상하는 과학이지만, 에이전트 시스템에서는 이미 필수적입니다. 모델이 더 강력해지고, 빨라지고, 저렴해지고 있지만, 아무리 뛰어난 능력도 메모리, 환경, 피드백의 필요성을 대체할 수 없습니다. 맥락을 어떻게 구성하느냐가 결국 에이전트의 행동 방식을 정의합니다: 얼마나 빠르게 실행되는지, 얼마나 잘 복구되는지, 그리고 얼마나 확장 가능한지를 결정합니다.
Manus에서 우리는 반복적인 재작성, 막다른 길, 수백만 사용자에 걸친 실제 테스트를 통해 이러한 교훈을 배웠습니다. 여기서 공유한 내용이 모두 보편적 진리는 아니지만, 이것들은 우리에게 효과가 있었던 패턴들입니다. 이 글이 여러분이 단 하나의 고통스러운 반복을 피하는 데 도움이 된다면, 이 글은 그 역할을 다한 것입니다.
에이전트의 미래는 맥락 하나하나로 구축될 것입니다. 잘 설계하세요.