AI 에이전트를 위한 컨텍스트 엔지니어링: Manus를 만들며 얻은 교훈

기능

리소스

영어

Deutsch Español Español (Latinoamérica) Français Italiano Português (Brasil) Português (Portugal) Tiếng Việt Türkçe 简体中文繁體中文日本語 한국어 العربية ไทย हिन्दी

시작하기

영어

Manus는 이제 Meta의 일원입니다

제품·7월 18일(금)

AI 에이전트를 위한 컨텍스트 엔지니어링: Manus를 만들며 얻은 교훈

2025/7/18 --Yichao 'Peak' Ji

Manus 프로젝트의 아주 초기에, 우리 팀은 중요한 결정을 내려야 했습니다. 오픈소스 기반 모델 위에서 엔드투엔드 에이전트형(agentic) 모델을 학습할 것인가, 아니면 최전선(frontier) 모델의 인컨텍스트 러닝 능력 위에 에이전트를 구축할 것인가?

제가 NLP에서 첫 10년을 보내던 시절에는 이런 선택의 여유가 없었습니다. BERT의 먼 옛날(네, 벌써 7년이 지났습니다)에는 모델이 새로운 작업으로 옮겨 가려면 반드시 파인튜닝을 하고(그리고 평가도 하고) 나서야 했습니다. 그 과정은 반복(iteration)마다 수주가 걸리곤 했습니다. 오늘날의 LLM에 비하면 모델이 아주 작았는데도 말이죠. 빠르게 움직여야 하는 애플리케이션, 특히 PMF 이전 단계에서는 이런 느린 피드백 루프가 치명적입니다. 이는 제가 지난 스타트업에서 오픈 정보 추출과 시맨틱 서치를 위해 모델을 처음부터 학습하며 얻은 쓰라린 교훈이었습니다. 그러다 GPT-3와 Flan-T5가 등장했고, 제 사내 모델은 하룻밤 사이에 무의미해졌습니다. 아이러니하게도, 바로 그 모델들이 인컨텍스트 러닝의 시작—그리고 완전히 새로운 전진 경로—을 열었습니다.

그렇게 뼈아프게 얻은 교훈은 선택을 분명하게 만들었습니다. Manus는 컨텍스트 엔지니어링에 베팅하기로 했습니다. 이를 통해 우리는 수주가 아니라 수시간 단위로 개선을 배포할 수 있었고, 제품을 기반 모델과 직교(orthogonal)하게 유지할 수 있었습니다. 모델의 발전이 밀물이라면, Manus는 해저에 박힌 기둥이 아니라 배가 되고 싶었습니다.

하지만 컨텍스트 엔지니어링은 결코 단순하지 않았습니다. 이는 실험 과학(experimental science)이며, 우리는 컨텍스트를 더 잘 다듬는 방법을 발견할 때마다 에이전트 프레임워크를 네 번이나 다시 만들었습니다. 아키텍처를 탐색하고, 프롬프트를 조정하고, 경험적 추측을 반복하는 이 수작업 과정을 우리는 애정 어린 농담으로 “확률적 대학원 하강법(Stochastic Graduate Descent)”이라고 부릅니다. 우아하진 않지만, 작동합니다.

이 글은 우리만의 “SGD”를 통해 도달한 로컬 옵티마(local optima)를 공유합니다. 여러분이 AI 에이전트를 만들고 있다면, 이 원칙들이 더 빨리 수렴하는 데 도움이 되길 바랍니다.

KV-캐시를 중심으로 설계하라

제가 딱 하나의 지표만 고르라면, 프로덕션 단계 AI 에이전트에서 KV-캐시 적중률(hit rate)이 가장 중요한 단일 지표라고 주장하겠습니다. 이는 지연 시간(latency)과 비용(cost) 모두에 직접적인 영향을 미칩니다. 이유를 이해하기 위해, 전형적인 에이전트가 어떻게 동작하는지 보겠습니다.

사용자 입력을 받은 뒤, 에이전트는 작업을 완료하기 위해 일련의 도구(tool) 사용 체인을 진행합니다. 각 반복(iteration)에서 모델은 현재 컨텍스트를 바탕으로 미리 정의된 액션 공간(action space)에서 하나의 액션을 선택합니다. 그 액션은 환경(예: Manus의 가상 머신 샌드박스)에서 실행되어 관측(observation)을 생성합니다. 액션과 관측은 컨텍스트에 덧붙여져 다음 반복의 입력이 됩니다. 이 루프는 작업이 완료될 때까지 계속됩니다.

상상하실 수 있듯, 컨텍스트는 매 단계마다 커지지만 출력은(대개 구조화된 함수 호출) 상대적으로 짧게 유지됩니다. 그래서 에이전트에서는 챗봇에 비해 프리필(prefilling)과 디코딩(decoding) 비율이 크게 한쪽으로 치우칩니다. 예를 들어 Manus의 평균 입력:출력 토큰 비율은 약 100:1입니다.

다행히도 동일한 접두(prefix)를 가진 컨텍스트는 KV-캐시를 활용할 수 있어, 첫 토큰까지의 시간(TTFT)과 추론 비용을 크게 줄입니다. 자체 호스팅 모델이든 추론 API 호출이든 마찬가지입니다. 그리고 이것은 소소한 절감이 아닙니다. 예를 들어 Claude Sonnet의 경우 캐시된 입력 토큰은 0.30 USD/MTok, 캐시되지 않은 입력 토큰은 3 USD/MTok로, 10배 차이가 납니다.

컨텍스트 엔지니어링 관점에서 KV-캐시 적중률을 높이려면 몇 가지 핵심 실천이 필요합니다.

1.프롬프트 접두를 안정적으로 유지하라. LLM의 자기회귀적(autoregressive) 성질 때문에, 단 한 토큰의 차이만 있어도 그 토큰 이후의 캐시는 무효화될 수 있습니다. 흔한 실수는 시스템 프롬프트 시작 부분에 타임스탬프—특히 초 단위로 정밀한 값—를 넣는 것입니다. 모델이 현재 시간을 말해줄 수는 있지만, 캐시 적중률은 박살납니다.

2.컨텍스트는 append-only로 만들어라. 이전 액션이나 관측을 수정하지 마세요. 직렬화(serialization)가 결정적(deterministic)임을 보장하세요. 많은 언어와 라이브러리는 JSON 객체를 직렬화할 때 키 순서가 안정적이라는 보장을 하지 않으며, 이는 조용히 캐시를 깨트릴 수 있습니다.

3.필요할 때 캐시 브레이크포인트를 명시적으로 표시하라. 일부 모델 제공자나 추론 프레임워크는 자동 증분(prefix) 캐싱을 지원하지 않고, 컨텍스트에 캐시 브레이크포인트를 수동으로 삽입해야 합니다. 이를 할당할 때는 캐시 만료 가능성을 고려하고, 최소한 브레이크포인트가 시스템 프롬프트의 끝을 포함하도록 하세요.

추가로, vLLM 같은 프레임워크로 모델을 자체 호스팅한다면, prefix/prompt caching이 활성화되어 있는지 확인하고, 분산 워커 전반에 걸쳐 요청을 일관되게 라우팅하기 위해 세션 ID 같은 기법을 사용하세요.

제거하지 말고, 마스킹하라

에이전트가 더 많은 기능을 맡게 되면, 액션 공간은 자연스럽게 더 복잡해집니다. 평범한 말로 하면 도구 수가 폭발합니다. 최근 MCP가 인기를 끈 것도 불에 기름을 붓습니다. 사용자가 도구를 구성할 수 있게 해두면, 장담컨대 누군가는 여러분이 정성스럽게 큐레이션한 액션 공간에 수백 개의 정체불명 도구를 꽂아 넣을 것입니다. 그러면 모델은 잘못된 액션을 선택하거나 비효율적인 경로를 택할 가능성이 커집니다. 요컨대, 무장한 에이전트가 더 멍청해집니다.

자연스러운 반응은 동적 액션 공간을 설계하는 것입니다. 예컨대 RAG 비슷한 방식으로 필요할 때 도구를 로드하는 것이죠. Manus에서도 이를 시도했습니다. 하지만 실험 결과는 명확한 규칙을 시사합니다. 꼭 필요하지 않다면, 반복 중간에 도구를 동적으로 추가/제거하는 일을 피하세요. 이유는 두 가지입니다.

1.대부분의 LLM에서 도구 정의는 직렬화 후 컨텍스트의 앞부분, 보통 시스템 프롬프트 전후에 위치합니다. 따라서 변경이 생기면 이후의 모든 액션과 관측에 대한 KV-캐시가 무효화됩니다.

2.이전 액션과 관측이 더 이상 정의되지 않은 도구를 참조하고 있으면 모델이 혼란을 겪습니다. 제약 디코딩(constrained decoding)이 없다면 스키마 위반이나 환각(hallucinated) 액션으로 이어지는 경우가 많습니다.

이를 해결하면서도 액션 선택을 개선하기 위해, Manus는 컨텍스트 인지형 상태 머신을 사용해 도구 가용성을 관리합니다. 도구를 제거하는 대신, 디코딩 중 토큰 로짓(logits)을 마스킹하여 현재 컨텍스트에 따라 특정 액션의 선택을 방지(또는 강제)합니다.

실제로 대부분의 모델 제공자와 추론 프레임워크는 응답 프리필(response prefill) 형태를 지원해, 도구 정의를 수정하지 않고도 액션 공간을 제약할 수 있습니다. 일반적으로 함수 호출(function calling)에는 세 가지 모드가 있습니다(여기서는 NousResearch의 Hermes 포맷을 예로 들겠습니다).

•Auto – 모델이 함수 호출을 할 수도, 안 할 수도 있습니다. 답변 접두만 프리필하여 구현합니다: <|im_start|>assistant

•Required – 모델이 반드시 함수를 호출해야 하지만, 선택은 제약되지 않습니다. 도구 호출 토큰까지 프리필하여 구현합니다: <|im_start|>assistant<tool_call>

•Specified – 모델이 특정 부분집합의 함수 중 하나를 반드시 호출해야 합니다. 함수 이름 시작까지 프리필하여 구현합니다: <|im_start|>assistant<tool_call>{"name": “browser_

이를 이용해 우리는 토큰 로짓을 직접 마스킹해 액션 선택을 제약합니다. 예를 들어 사용자가 새 입력을 제공하면, Manus는 액션을 취하기보다 즉시 응답해야 합니다. 또한 액션 이름을 일관된 접두(prefix)로 설계했습니다. 예컨대 브라우저 관련 도구는 모두 browser_로, 커맨드라인 도구는 shell_로 시작합니다. 이렇게 하면 상태를 가진 로짓 프로세서(stateful logits processors)를 쓰지 않고도, 특정 상태에서 에이전트가 특정 도구 그룹에서만 선택하도록 쉽게 강제할 수 있습니다.

이러한 설계는 모델 주도 아키텍처 하에서도 Manus 에이전트 루프가 안정적으로 유지되도록 돕습니다.

파일 시스템을 컨텍스트로 사용하라

현대의 최전선 LLM은 이제 128K 토큰 이상의 컨텍스트 윈도우를 제공합니다. 하지만 실제 에이전트 시나리오에서는 그 정도로도 부족한 경우가 많고, 때로는 오히려 부담이 되기도 합니다. 대표적인 문제는 세 가지입니다.

1.관측이 매우 커질 수 있습니다. 특히 웹페이지나 PDF처럼 비정형 데이터와 상호작용할 때는 컨텍스트 한도를 쉽게 초과합니다.

2.기술적으로 윈도우가 지원되더라도, 일정 컨텍스트 길이를 넘어서면 모델 성능이 저하되는 경향이 있습니다.

3.프리픽스 캐싱이 있어도 긴 입력은 비쌉니다. 매 토큰을 전송하고 프리필하는 비용을 여전히 치릅니다.

이를 해결하기 위해 많은 에이전트 시스템은 컨텍스트 절단(truncation)이나 압축(compression) 전략을 구현합니다. 하지만 지나치게 공격적인 압축은 필연적으로 정보 손실을 초래합니다. 문제는 근본적입니다. 에이전트는 본질적으로 모든 이전 상태를 바탕으로 다음 행동을 예측해야 하며, 어떤 관측이 10단계 뒤에 결정적으로 중요해질지 신뢰할 수 있게 예측할 수 없습니다. 논리적으로도, 되돌릴 수 없는(irreversible) 압축은 언제나 위험을 동반합니다.

그래서 우리는 Manus에서 파일 시스템을 궁극의 컨텍스트로 취급합니다. 크기 제한이 없고, 본질적으로 영속적이며, 에이전트가 직접 조작할 수 있기 때문입니다. 모델은 필요할 때 파일에 쓰고 읽는 법을 학습하며, 파일 시스템을 단순한 저장소가 아니라 구조화된 외부 메모리(externalized memory)로 사용합니다.

우리의 압축 전략은 언제나 복원 가능(restorable)하도록 설계됩니다. 예컨대 웹페이지의 내용은 URL만 보존한다면 컨텍스트에서 제거해도 되고, 문서의 내용 역시 샌드박스 내 경로가 남아 있다면 생략할 수 있습니다. 이렇게 하면 Manus는 정보를 영구히 잃지 않으면서 컨텍스트 길이를 줄일 수 있습니다.

이 기능을 개발하면서, 저는 에이전트 환경에서 상태공간모델(SSM, State Space Model)이 효과적으로 동작하려면 무엇이 필요할지 상상하곤 했습니다. 트랜스포머와 달리 SSM은 완전한 어텐션이 없고 장거리 역방향 의존성(long-range backward dependencies)에 약합니다. 하지만 파일 기반 메모리를 숙달해, 장기 상태를 컨텍스트에 담아두는 대신 외부화할 수 있다면, 그 속도와 효율은 새로운 종류의 에이전트를 열어줄지도 모릅니다. 에이전트형 SSM은 Neural Turing Machine의 진정한 후계자가 될 수 있습니다.

‘되뇌기’로 어텐션을 조작하라

Manus를 써본 적이 있다면, 복잡한 작업을 처리할 때 todo.md 파일을 만들고 작업이 진행됨에 따라 단계별로 업데이트하며 완료한 항목을 체크하는 모습을 본 적이 있을 것입니다.

그건 단지 귀여운 습관이 아닙니다. 의도적으로 어텐션을 조작하는 메커니즘입니다.

Manus에서 전형적인 작업은 평균 약 50회의 도구 호출을 필요로 합니다. 이는 긴 루프입니다. 그리고 Manus는 의사결정에 LLM을 의존하기 때문에, 특히 컨텍스트가 길거나 작업이 복잡할수록 주제가 흐트러지거나 초기 목표를 잊어버리는 드리프트(drift)에 취약합니다.

할 일 목록을 계속 다시 쓰면서, Manus는 목표를 컨텍스트의 끝부분에 되뇌고(recite) 있습니다. 이는 전역 계획(global plan)을 모델의 ‘최근 어텐션 범위’로 밀어 넣어, “lost-in-the-middle” 문제를 피하고 목표 불일치를 줄입니다. 사실상 이는 특별한 아키텍처 변경 없이도, 자연어로 스스로의 초점을 작업 목표 쪽으로 편향(bias)시키는 방식입니다.

‘틀린 것’을 컨텍스트에 남겨라

에이전트는 실수합니다. 버그가 아니라 현실입니다. 언어 모델은 환각을 하고, 환경은 에러를 반환하며, 외부 도구는 오작동하고, 예상치 못한 엣지 케이스는 언제나 나타납니다. 다단계 작업에서 실패는 예외가 아니라 루프의 일부입니다.

그럼에도 흔한 충동은 이런 오류를 숨기는 것입니다. 트레이스를 정리하고, 액션을 재시도하고, 모델 상태를 리셋한 뒤 마법의 “temperature”에 맡기는 식이죠. 더 안전하고 통제된 느낌이 듭니다. 하지만 대가가 있습니다. 실패를 지우면 증거도 사라집니다. 그리고 증거가 없으면 모델은 적응할 수 없습니다.

우리 경험상, 에이전트 행동을 개선하는 가장 효과적인 방법 중 하나는 놀라울 정도로 단순합니다. 잘못된 선택을 컨텍스트에 그대로 남겨두는 것입니다. 모델이 실패한 액션과 그 결과 관측(또는 스택 트레이스)을 보면, 암묵적으로 내부 신념을 업데이트합니다. 이는 유사한 액션들에 대한 사전(prior)을 이동시켜, 같은 실수를 반복할 확률을 낮춥니다. 사실 우리는 오류 복구(error recovery)가 진정한 에이전트적 행동을 보여주는 가장 분명한 지표 중 하나라고 믿습니다. 하지만 학계 연구나 공개 벤치마크에서는 아직 충분히 다뤄지지 않았습니다. 대부분 이상적인 조건에서의 작업 성공에 초점을 맞추기 때문입니다.

Few-shot에 당하지 마라

Few-shot 프롬프팅은 LLM 출력을 개선하는 흔한 기법입니다. 하지만 에이전트 시스템에서는 미묘한 방식으로 역효과를 낼 수 있습니다.

언어 모델은 뛰어난 모방자입니다. 컨텍스트 안의 행동 패턴을 모방합니다. 컨텍스트가 과거의 유사한 액션-관측 쌍으로 가득 차 있으면, 더 이상 최적이 아니어도 그 패턴을 계속 따르려는 경향이 생깁니다.

이는 반복적인 결정이나 행동이 포함된 작업에서 위험할 수 있습니다. 예를 들어 Manus로 20개의 이력서를 일괄 검토하도록 하면, 에이전트가 종종 리듬에 빠져들어 컨텍스트에 보이는 대로 유사한 행동을 반복합니다. 그 결과 드리프트, 과도한 일반화, 때로는 환각으로 이어집니다.

해결책은 다양성을 늘리는 것입니다. Manus는 액션과 관측에 소량의 구조화된 변형을 도입합니다. 서로 다른 직렬화 템플릿, 대체 표현, 순서나 서식에 약간의 노이즈를 주는 방식입니다. 이런 통제된 랜덤성은 패턴을 깨고 모델의 어텐션을 미세 조정하는 데 도움이 됩니다. 다시 말해, few-shot으로 스스로를 ‘홈(홈성 루틴)’에 빠뜨리지 마세요. 컨텍스트가 균질할수록 에이전트는 더 취약해집니다.

결론

컨텍스트 엔지니어링은 아직 떠오르는 과학이지만, 에이전트 시스템에서는 이미 필수입니다. 모델은 더 강력해지고, 더 빨라지고, 더 저렴해질 수 있지만, 어떤 ‘순수한 능력’도 메모리, 환경, 피드백의 필요성을 대체하지는 못합니다. 컨텍스트를 어떻게 빚어내느냐가 결국 에이전트의 행동을 규정합니다. 얼마나 빠르게 실행되는지, 얼마나 잘 복구하는지, 얼마나 멀리 확장되는지 말이죠.

Manus에서는 수차례의 리라이트, 막다른 길, 수백만 사용자에 걸친 실전 테스트를 통해 이 교훈들을 배웠습니다. 여기서 공유한 내용이 보편적 진리인 것은 아닙니다. 하지만 우리에게 효과가 있었던 패턴들입니다. 이것들이 여러분이 고통스러운 반복을 단 한 번이라도 줄이는 데 도움이 된다면, 이 글은 제 역할을 한 것입니다.

에이전트의 미래는 한 번에 하나의 컨텍스트로 만들어질 것입니다. 컨텍스트를 잘 설계하세요.

구조는 줄이고,