LangChain Deep Agents는 2만 토큰이 넘는 도구 결과를 파일로 빼고 85%에서 대화를 요약합니다 | DAKER 커뮤니티

에이전트에게 긴 작업을 맡기면 처음에 준 지시를 뒤에서 잊거나, 앞에서 확인한 숫자를 틀리게 다시 말하는 순간이 옵니다. LangChain이 10월 21일 공식 유튜브 채널 LangChain에 올린 5분짜리 설명 영상 「How Deep Agents Manages Context: Offloading and Summarization」은 이 문제를 오픈소스 에이전트 하네스 Deep Agents가 어떻게 다루는지 두 가지 장치로 보여 줍니다. 2만 토큰이 넘는 도구 결과는 모델에게 통째로 보내지 않고 파일로 빼 두며, 대화가 모델 입력 한도의 85%를 넘으면 앞부분을 요약으로 바꿉니다. 해커톤에서 에이전트를 만드는 팀이 오늘 바로 확인할 것은 하나입니다. 내 에이전트의 도구 결과 가운데 가장 큰 것이 몇 토큰인지 로그에서 재 보는 일입니다.

크레용으로 그린 책상 위 장면입니다. 왼쪽 서류 캐비닛 서랍에 긴 두루마리가 들어가고, 가운데 유리병에는 색종이 쪽지가 가득 차 있으며, 오른쪽에는 빨간 리본으로 묶은 카드 묶음이 놓여 있습니다. 긴 도구 결과를 파일로 빼고 오래된 대화를 요약해 묶는 컨텍스트 정리를 나타냅니다.
설명용 생성 이미지입니다.

Deep Agents 영상이 말하는 컨텍스트 부패란 무엇입니까

영상은 시험 전날 벼락치기에 비유하며 시작합니다. 공부를 많이 할수록 앞 장의 내용이 흐려지듯, 에이전트도 작업이 길어질수록 지시문과 도구 결과가 쌓이고 결국 모델의 컨텍스트 창에 편하게 들어갈 양을 넘깁니다. 영상의 표현을 옮기면 모델이 들고 다니는 기록과 잡음, 도구 출력이 많을수록 추론과 정확도가 나빠지는 경향이 있습니다. LangChain은 이 현상을 컨텍스트 부패(context rot)라고 부릅니다.

영상은 에이전트를 모델 더하기 하네스로 정의합니다. 하네스는 모델을 감싸고 도구 호출, 파일 접근, 메시지 관리를 맡는 실행 틀이고, 그 역할은 적절한 시점에 적절한 정보를 모델에게 건네는 것입니다. 영상은 대응 방법을 두 갈래로 나눕니다.

첫째의 대표가 오프로딩(offloading), 둘째의 대표가 요약(summarization)입니다. Deep Agents는 이 둘에 더해 스킬, 서브에이전트, 장기 기억을 기본 기능으로 제공한다고 영상은 설명합니다. 모델을 바꾸기 전에 하네스가 무엇을 모델 앞에 놓는지부터 보라는 메시지입니다.

오프로딩: 2만 토큰이 넘는 도구 결과는 파일로 빼 둡니다

영상 속 예시는 데이터베이스 조회 도구 query_db입니다. 사용자가 무언가를 조회해 달라고 하자 에이전트가 이 도구를 불렀고, 돌아온 결과는 2만 토큰이 넘었습니다. Deep Agents는 이 결과를 가상 파일 시스템의 large_tool_results 폴더에 저장하고, 모델에게는 결과의 일부만 미리보기로 보여 줍니다. 모델은 더 필요하면 파일 읽기 도구로 전체 결과를 넘겨 가며 읽을 수 있습니다. 원본은 언제든 다시 꺼낼 수 있지만, 매번 모델에게 보내지는 않는 구조입니다.

LangChain의 Deep Agents 공식 문서(Context engineering in Deep Agents)는 같은 동작을 조금 더 구체적으로 적어 둡니다. 도구 결과가 기본값 2만 토큰을 넘으면 결과를 설정된 저장소로 옮기고, 그 자리에 파일 경로와 처음 10줄 미리보기를 남깁니다. 반대 방향도 있습니다. 파일 쓰기나 편집 도구에 2만 토큰이 넘는 내용이 입력으로 들어간 경우, 그 내용은 이미 파일로 저장돼 있으므로 컨텍스트가 85%를 넘을 때 오래된 도구 호출을 잘라 내고 파일 위치만 남깁니다.

오프로딩은 도구 결과에만 쓰이지 않습니다. 영상은 사용자가 붙여 넣은 긴 비자 서류나 회의록 같은 긴 메시지도 같은 원리로 처리한다고 설명합니다. 이때 기준은 조금 높은 5만 토큰이고, 저장 위치는 large_tool_results가 아니라 conversation_history 폴더입니다. 모델은 역시 미리보기만 받습니다.

해커톤 팀에게 이 장치가 의미하는 바는 분명합니다. 공시 원문, 검색 결과 목록, 데이터베이스 조회 결과처럼 큰 출력을 돌려주는 도구가 있다면 그 출력은 모델이 다 읽어야 할 글이 아니라 필요할 때 펼쳐 보는 첨부 파일로 다루는 편이 낫습니다. 도구를 설계할 때부터 결과가 얼마나 커질 수 있는지, 미리보기에 무엇을 남길지 정해 두면 에이전트가 뒤에서 앞 내용을 놓치는 일이 줄어듭니다.

요약: 85%를 넘으면 앞부분을 요약으로 바꾸고 원문은 보관합니다

오프로딩을 아무리 잘해도 긴 작업에서는 컨텍스트가 조금씩 쌓입니다. 이때 요약이 나섭니다. 요약은 지금까지의 대화를 압축한 판본으로 바꿔, 에이전트가 다른 일을 계속할 여유를 만들어 줍니다. 영상은 오른쪽에 토큰 사용량 막대를 띄워 놓고 메시지가 쌓일수록 막대가 올라가는 모습을 보여 줍니다.

영상에서 짚을 만한 세부는 세 가지입니다.

  1. 85%는 기본값일 뿐이며, 요약이 더 낮거나 높은 사용량에서 시작하도록 조정할 수 있습니다.
  2. 요약 여부는 모델을 부르기 직전마다 한 번씩 검사합니다. 그래서 도구 호출이 여러 번 이어지는 구간에서는 검사와 검사 사이에 컨텍스트가 크게 늘어 사용량이 85%를 넘어선 뒤에야 요약이 실행되기도 합니다.
  3. 보존 기준선(keep cutoff) 위의 메시지는 요약되고, 아래의 최근 메시지는 요약 뒤에 원문 그대로 붙습니다. 요약된 메시지도 conversation_history에 저장돼 필요하면 다시 찾아볼 수 있습니다.

요약은 한 번으로 끝나지 않습니다. 대화가 다시 쌓이면 같은 과정이 반복되고, 두 번째 요약에는 첫 번째 요약이 포함됩니다. 영상은 이 흐름을 고리처럼 이어지는 과정으로 설명합니다.

공식 문서에 적힌 기본 설정도 함께 보면 감이 잡힙니다. 요약은 모델 프로필에 적힌 max_input_tokens의 85%에서 시작하고, 최근 컨텍스트로 토큰의 10%를 남깁니다. 모델 프로필을 알 수 없으면 17만 토큰에서 시작하고 최근 메시지 6개를 남기는 값으로 돌아갑니다. 모델 호출이 컨텍스트 초과 오류를 내면 즉시 요약으로 넘어가 요약과 최근 메시지로 다시 시도합니다. 문서는 요약이 세션의 의도, 만든 산출물, 다음 단계를 담은 구조화된 요약이라고 설명하며, 원래 대화는 텍스트로 파일 시스템에 남겨 둔다고 밝힙니다.

문서에는 자동 요약 말고 수동 장치도 하나 있습니다. compact_conversation 도구를 켜면 에이전트가 85%를 기다리지 않고 작업과 작업 사이에 스스로 압축을 실행할 수 있습니다. 이 도구를 켜도 85% 자동 요약은 그대로 동작합니다.

두 장치는 어떻게 함께 움직입니까

영상은 마지막에 두 장치를 한 그래프로 정리합니다. 컨텍스트 사용량은 전반적으로 조금씩 올라가고, 중간에 작게 튀어 오르는 부분이 오프로딩입니다. 큰 결과가 들어왔지만 미리보기만 컨텍스트에 들어갔기 때문에 작게만 오른 것입니다. 그리고 피할 수 없이 쌓이는 부분은 요약이 한 번씩 크게 덜어 냅니다. 영상의 정리를 그대로 옮기면, 오프로딩은 입력이 컨텍스트에 들어오기 전에 가로채고 요약은 이미 컨텍스트에 있는 내용에 작동합니다.

두 장치에는 공통점이 있습니다. 어느 쪽도 정보를 버리지 않습니다. 오프로딩된 도구 결과는 large_tool_results에, 요약된 대화와 긴 사용자 메시지는 conversation_history에 남습니다. 모델이 지금 보는 것은 줄이되, 필요하면 다시 찾을 수 있게 하는 설계입니다. 에이전트를 직접 만들 때도 이 원칙을 지키면, 요약 과정에서 숫자 하나가 빠져 생기는 오류를 원문 파일로 되짚을 수 있습니다.

영상이 다루지 않은 부분도 분명히 해 둡니다. 영상은 동작 방식을 설명하는 시연이며, 오프로딩이나 요약을 켰을 때 정답률이 몇 퍼센트 오르는지 같은 성능 수치는 제시하지 않습니다. 85%와 2만 토큰이 모든 작업에 가장 좋은 값이라는 근거도 영상에는 없습니다. 내 작업에 맞는 값은 직접 재 봐야 합니다.

해커톤 에이전트 팀이 오늘 해 볼 일

Deep Agents를 쓰든, 다른 프레임워크를 쓰든, 직접 하네스를 짜든 아래 순서는 그대로 적용됩니다.

  1. 지난 실행 로그에서 도구별 결과 크기를 토큰 단위로 뽑습니다. 가장 큰 도구 세 개가 무엇인지, 그 결과가 한 번에 몇 토큰인지 적어 둡니다.
  2. 기준을 넘는 결과는 파일로 저장하고 모델에게는 경로와 미리보기만 넘깁니다. Deep Agents의 기본값인 2만 토큰을 출발점으로 삼고, 미리보기에 남길 줄 수를 정합니다.
  3. 요약 시작 지점을 정하고, 모델 호출 직전에 검사한다는 점을 감안해 도구 호출이 몰리는 구간에서 사용량이 얼마나 넘치는지 확인합니다.
  4. 요약 뒤에도 원문을 찾을 수 있는지 시험합니다. 긴 실행을 한 번 돌린 뒤, 앞부분에서 나온 숫자 하나를 에이전트에게 다시 묻고 파일에서 찾아 맞게 답하는지 봅니다.
  5. 결과 크기, 기준값, 시험 결과를 저장소의 README나 AGENTS.md 같은 문서에 남깁니다. 팀원이 값을 바꿀 때 근거가 됩니다.

넷째 항목이 특히 중요합니다. 요약은 모델이 만드는 글이라 숫자나 고유명사가 빠질 수 있습니다. 금융 데이터처럼 숫자 하나가 답을 바꾸는 과제라면, 요약이 아니라 원문 파일에서 숫자를 다시 읽어 오는지 확인하는 시험 질문을 몇 개 만들어 두는 편이 안전합니다.

KIC AI Agent 공모전 기획서와 본선에는 어떻게 이어집니까

DAKER에서 진행 중인 국부펀드 KIC, AI 에이전트 공모전은 투자와 금융 업무를 돕는 AI Agent를 기획하고 실제 작동하는 MVP로 구현하는 대회입니다. 대회 페이지 기준으로 10월 26일 오전 참가자는 591명, 제출은 75건이며, 기획안 제출은 11월 12일 오전 10시에 닫힙니다. 예선을 통과한 팀의 본선 산출물 제출 기간은 12월 3일 오전 10시부터 12월 22일 오전 10시까지입니다.

공시, 리포트, 시세 기록처럼 큰 문서를 읽는 금융 에이전트는 도구 결과가 커지기 쉬운 유형입니다. 기획서의 Workflow를 그릴 때 어떤 도구 결과를 파일로 빼고, 긴 대화를 언제 요약하며, 원문은 어디에 남기는지를 한 단계로 넣어 두면 에이전트가 긴 작업에서 어떻게 정확도를 지키는지 설명하기 쉬워집니다. 무엇을 기억하고 언제 지울지를 Workflow에 함께 그리는 방법은 DAKER 글 어제 물은 종목을 기억하는 KIC AI Agent라면 기획서 Workflow에 저장할 것과 지울 때를 함께 그립니다에서도 다뤘습니다. 평가 기준과 제출 형식은 반드시 대회 페이지의 공식 안내를 기준으로 확인하십시오.

긴 세션에서 컨텍스트가 차오르는 문제를 코딩 도구 쪽에서 본 글로는 DAKER 잡담의 Claude Code 모드가 생겼습니다: 해커톤 세션이 길어질수록 차오르는 컨텍스트를 프롬프트 위 한 줄 계기판으로 먼저 봅니다가 있습니다. 그 글이 컨텍스트 사용량을 눈으로 보는 방법이라면, 이번 영상은 하네스가 사용량을 직접 줄이는 방법입니다.

자주 묻는 질문

Deep Agents를 쓰지 않아도 이 방법을 적용할 수 있습니까?

적용할 수 있습니다. 영상이 보여 주는 것은 특정 라이브러리 기능이기 전에 하네스 설계 원칙입니다. 큰 도구 결과를 파일로 저장하고 경로와 미리보기만 모델에게 넘기는 일, 사용량이 기준을 넘으면 앞부분을 요약하고 원문을 보관하는 일은 직접 만든 에이전트 루프에도 넣을 수 있습니다.

85%와 2만 토큰은 그대로 써도 됩니까?

출발점으로는 쓸 수 있지만 최적값이라는 근거는 영상에 없습니다. 영상도 85%는 기본값이며 조정할 수 있다고 설명합니다. 도구 결과 크기와 모델의 입력 한도에 따라 값을 바꾸고, 바꾼 뒤에는 앞부분 숫자를 다시 묻는 시험으로 정확도를 확인하십시오.

요약하면 정보가 사라지지 않습니까?

Deep Agents는 요약된 메시지를 conversation_history에 저장해 두고 필요하면 다시 찾게 합니다. 다만 모델이 지금 보는 것은 요약이므로, 요약에서 빠진 세부를 에이전트가 스스로 파일에서 찾아오는지는 직접 시험해야 합니다.

출처