
처음으로 Agent의 메인 체인을 끝까지 돌렸을 때, 나는 가장 어려운 부분이 끝났다고 생각했습니다.
모델을 호출할 수 있고, 데이터를 DB에 저장할 수 있고, 벡터를 검색할 수 있고, 워크플로도 끝까지 순조롭게 진행되었습니다. LangGraph로 처음 완전한 프로젝트를 만드는 사람에게 이것만으로도 한동안 흥분하기에 충분했습니다.
하지만 실제로 연속 사용을 시작하자 문제가 하나씩 드러났습니다: 분명히 checkpoint를 설정했는데도 다음 턴에서 모델이 이전 턴에 무슨 일이 있었는지 모릅니다; 워크플로를 아주 세밀하게 나눴는데 상태에는 저장할 필요 없는 중간 산출물이 가득합니다; 데이터베이스에 정보를 꽤 많이 저장했지만 모델이 받는 컨텍스트가 반드시 유용한 것은 아닙니다.
더 힘들었던 것은, 제품 요구사항이 바뀔 때마다 나는 항상 먼저 왜 현재 아키텍처가 이 요구사항을 잘 지원하지 못하는지 설명한 다음, 어떻게든 억지로 밀어 넣을 방법을 찾아야 했다는 점입니다.
그래서 나는 다시 작성하기로 했습니다.
논의를 쉽게 하기 위해 아래에서는 프로젝트의 구체적인 업무를 숨기고, 지속적으로 컨텍스트를 축적하고 다중 턴 상호작용을 지원해야 하는 대화형 Agent로 보겠습니다. 이 글도 기술 스택을 나열하려는 것이 아니라, 나를 실제로 막혔던 지점들과 그 문제들이 Agent 개발에 대한 나의 이해를 어떻게 바꿨는지 이야기하고 싶습니다.
1. 나는 워크플로 상태를 모델의 기억으로 착각했다
초기 아키텍처는 비교적 긴 Pipeline이었습니다: 비즈니스 객체 로드, 기초 자료 정리, 검색 query 구성, 정보 검색, 컨텍스트 구성, 마지막으로 모델 호출.
노드 간에 데이터를 편하게 전달하기 위해, 도중에 생성된 거의 모든 것을 Graph State에 넣었습니다. 조회 결과, 검색 query, 절반쯤 구성된 컨텍스트, 심지어 SQLAlchemy의 ORM 인스턴스까지 모두 집어넣었습니다.
당시 이해는 간단했습니다: State는 노드 간에 공유되는 데이터 아닌가? 넣어두면 다음 노드에서 바로 꺼내 쓰면 되니 얼마나 편한가.
checkpoint를 연결하고 나서 문제가 생겼습니다.
먼저 직렬화입니다. ORM 인스턴스는 일반 딕셔너리처럼 당시 checkpoint 직렬화 체인에 그대로 넘길 수 없었습니다. 다음은 영속화 범위입니다: 이번 실행에서만 유용한 임시 데이터도 상태와 함께 저장되었습니다.
처음 수정 방법은 마지막 노드에서 중간 필드를 비우는 것이었습니다. 그런데 나중에야 깨달았습니다. checkpoint는 실행 과정에서 상태를 기록하므로, 마지막에 한 번 비운다고 해서 앞서 이미 기록된 스냅샷이 사라지는 것은 아닙니다.
하지만 이것이 가장 큰 함정은 아니었습니다.
연속 질문을 지원하기 위해, 나는 두 번째 턴에서 첫 번째 턴에 저장된 컨텍스트를 그대로 재사용하여 시간이 오래 걸리는 구성 과정을 생략하고 싶었습니다. 동일한 thread_id를 설정하고 이어서 Graph를 호출했지만, 결과적으로 모델은 여전히 이전 턴을 본 적이 없는 것처럼 행동했습니다.
체인을 자세히 보면 이유는 사실 아주 명백합니다: 상태는 복원되었지만, 내가 모델을 호출할 때 새 HumanMessage 하나만 구성했습니다. 역사 정보는 State에 누워 있었고 이번 요청에 조직되지 않았으므로 모델은 당연히 볼 수 없었습니다.
더 황당한 것은 두 번째 턴 입력에서 컨텍스트 필드에 빈 문자열을 전달했다는 점입니다. 원래는 '이번 턴에는 다시 계산하지 않는다'는 뜻을 표현하려 했지만, 실제 효과는 빈 값으로 기존 상태를 덮어쓴 것이었습니다……
이 일 이후에야 나는 몇 가지를 진정으로 구분하게 되었습니다:
| 데이터 | 시스템에서의 책임 |
|---|---|
| 노드 내부의 임시 변수 | 현재 단계를 완료하면 사용 후 버려도 됨 |
| Graph State | 노드 간에 전달되고 필요에 따라 복원되는 실행 상태 |
| 메시지 역사 | 다중 턴 상호작용에서 보존해야 하는 대화 내용 |
| 이번 모델 입력 | 현재 작업이 실제로 소비해야 하는 정보 |
checkpoint는 실행 상태 복원을 도울 수 있지만, 어떤 내용이 모델 입력으로 들어갈지는 여전히 내가 직접 설계해야 합니다. 반대로 State가 크다고 해서 매 요청이 반드시 많은 token을 소비한다는 뜻은 아닙니다; 이 내용들을 모델에 보내야만 입력 비용이 됩니다.
이 차이는 아주 기초적으로 보이지만, 나는 실제로 한 번 실패하고 나서야 이해했습니다.
나는 노드 구분도 다시 고려했습니다. 이전에는 거의 함수 하나마다 node 하나를 나눴고, 나중에는 또 다른 극단으로 가서 전체 체인을 다시 하나의 node에 넣기도 했습니다. 계속 해보고 나서야 깨달았습니다. 노드 경계는 실행 요구에 따라 정해져야 합니다: 독립적으로 관찰하거나, 분기 라우팅하거나, 병렬 스케줄링해야 하는 단계는 분리하는 것이 가치가 있습니다; 국소적으로만 사용되는 변환 로직은 일반 함수로 충분합니다.

2. 모델 처리가 느린 것은 때때로 내가 낸 문제가 너무 어려웠기 때문이다
초기에는 스크린샷에서 구조화된 기록을 복원해야 하는 입력 체인이 있었습니다.
나는 모델에게 각 메시지의 발화자, 내용, 시간을 식별하고 엄격한 JSON으로 정리하라고 요구했습니다. 정확성을 높이기 위해 사용자에게도 많은 제한을 추가했습니다: 스크린샷 순서대로 업로드, 시간 포함, 장수 제한 등등.
결과는 이상적이지 않았습니다. 한 번의 시도에서 두 장의 스크린샷을 처리하는 데 약 2분이 걸렸고, 여전히 시간 혼란, 발화자 뒤바뀜, 무효 내용이 존재했습니다.
첫 반응은 물론 prompt를 계속 조정하는 것이었습니다. 하지만 최종 용도를 다시 보면서, 나는 갑자기 깨달았습니다. 내가 원본 기록을 하나도 빠뜨리지 않고 복원할 필요가 없다는 것을.
다운스트림이 실제로 필요로 하는 것은: 이 자료가 어떤 주제를 중심으로 하는지, 어떤 보존할 가치가 있는 정보를 포함하는지, 그리고 그것들이 어떤 맥락에서 발생했는지입니다.
그래서 나는 데이터 입도를 '건별 원본 기록'에서 '하나의 주제를 중심으로 조직된 정보'로 조정했습니다. 모델은 더 이상 완전한 기록 복원 작업을 맡지 않으며, 후속 검색도 먼저 대량의 흩어진 메시지에서 의미를 다시 조립할 필요가 없습니다.
물론 이 방안에는 당시 대가도 있었습니다: 나는 사용자에게 단일 제출 자료가 가능한 한 같은 주제에 속하도록 요구했고, 이는 일부 분할 작업을 사용자에게 돌려준 셈입니다. 그것은 처리 부담을 줄였지만 입력 경험을 완전히 해결했다고는 할 수 없습니다.
이 일로 나는 모델을 최적화하기 전에 먼저 두 가지 질문을 하는 습관이 생겼습니다: 최종 기능은 도대체 어떤 정보를 필요로 하는가? 지금 모델에 요구하는 출력 입도가 실제 용도를 넘어서는가?
데이터베이스가 원본 기록을 담을 수 있다고 해서 모델이 반드시 그것을 건별로 재구성해야 하는 것은 아닙니다; 모델이 복잡한 구조를 출력할 수 있다고 해서 제품이 사용자에게 그 구조를 다 채울 때까지 기다리게 해야 한다는 뜻도 아닙니다.
3. 컨텍스트의 어려움은 '저장하기'에서 '이번 턴에 어떻게 쓸 것인가'로 이동했다
처음 기억을 만들 때 나의 관심은 주로 쓰기 측에 있었습니다: 자료를 어떻게 추출할지, 데이터를 어떻게 모델링할지, 텍스트를 어떻게 벡터화할지.
나중에 Markdown으로 컨텍스트를 조직하는 몇 가지 방안을 접하면서, 정보 분류와 표현에서 참고할 만한 점이 많다는 것을 발견했습니다. 하지만 내가 시험해 본 방안 중 일부 파일은 매 턴 반드시 읽어야 했고, 다른 파일은 필요에 따라 전량 로드했습니다.
자료가 적을 때는 이것이 아주 직접적입니다. 자료가 점점 많아지자 나는 걱정하기 시작했습니다. 매번 정보의 작은 부분만 필요로 하는데, 먼저 파일 전체를 로드해야 한다는 점입니다.
그래서 재구성할 때 나는 기초 자료를 유지하고, 더 세밀한 정보를 독립 항목으로 나누어 이후 질문에 따라 검색할 수 있도록 했습니다. 여기서 데이터베이스는 항목의 소속, 분류, 시간을 관리하고, 텍스트 내용은 모델이 이해해야 하는 의미를 표현합니다.
하지만 벡터 검색이 있다고 해서 문제가 저절로 사라지는 것은 아닙니다.
초기 검색은 주로 의미 거리에 의존했습니다. 나중에 점차 비즈니스 범위 필터링, 중요도 가중치, 그리고 일부 정보에 대한 시간 감쇠를 추가했습니다. 왜냐하면 '질문과 매우 유사함'과 '현재 답변에 적합함'은 같은 것이 아니기 때문입니다.
특히 시간.
나는 한때 시스템 프롬프트에 '현재 시간'만 넣었고, 나중에야 그것이 역사 메시지가 각각 언제 발생했는지 설명할 수 없다는 것을 깨달았습니다. 더 업스트림을 보면, 데이터베이스에 생성 시간이 있더라도 추출된 텍스트가 원본 자료의 연도, 시기 또는 단계를 잃어버리면 모델은 여전히 다른 시간에 발생한 유사한 일들을 쉽게 혼동합니다.
이후 조정은 두 부분으로 나뉘었습니다: 대화 메시지에 명시적으로 타임스탬프를 붙이고; 정보를 추출할 때 자료에서 확인 가능한 시간 앵커를 본문에 보존하며, 확정할 수 없는 시간은 보충해서 쓰지 않습니다.
이것은 단순히 정렬 공식을 조정하는 것보다 더 앞선 문제입니다. 시간 정보가 추출 시점에 사라지면 검색 단계에서 허공에서 찾아내기 어렵습니다.
또한 나는 지식 검색을 Tool로 캡슐화하여 모델이 언제 자료를 보충해야 하는지 판단하게 하고, 매 턴 기계적으로 전체 검색 세트를 실행하는 것을 피하려고 시도했습니다.
하지만 Tool Call은 또 다른 경계를 드러냈습니다: 모델은 현재 비즈니스 객체의 ID를 안정적으로 생성할 수 없습니다. 이 ID는 분명히 이미 시스템 실행 컨텍스트에 있는데도, 나는 모델에게 다시 추측하라고 요구하고 있었습니다.
결국 나는 도구 실행 전에 현재 컨텍스트에서 이미 확정된 매개변수를 주입했습니다. 모델은 검색이 필요한지, 무엇을 검색할지 결정할 수 있습니다; 현재 사용자가 누구인지, 어떤 객체를 조작 중인지, 접근 권한이 있는지는 프로그램이 결정하고 검증해야 합니다.
이 문제들을 해결하면서 나의 컨텍스트에 대한 이해는 '가능한 한 많이 수집하기'에서 점차 현재 작업을 위해 필요한 정보를 보존하고, 그것이 적절한 형태로 모델에 들어가게 하기로 바뀌었습니다.
각 변경이 실제로 효과를 얼마나 높였는지에 관해서는, 나는 충분히 체계적인 평가 데이터가 없어서 여기서 백분율을 지어내고 싶지 않습니다. 확인할 수 있는 것은, 나는 이제 어느 체인을 따라 문제를排查해야 하는지 알게 되었고, 더 이상 최종 답변만盯着提示词를 조정하지 않는다는 것입니다.
4. 디렉토리를 나눴다고 해서 진정으로 디커플링된 것은 아니다
과거에 Web 프로젝트를 할 때 나는 백엔드를 먼저 작성하고, HTTP 인터페이스로 감싼 다음, 마지막으로 프론트엔드에 호출하게 하는 것에 익숙했습니다. 이 Agent도 처음에는 비슷한 구조를 따랐고, 비즈니스 능력과 Web 서비스가 아주 가까이 있었습니다.
나중에 제품이 주로 IM으로 상호작용하게 되자, 나는 CLI를 추가하여 설정, 관리, 진단 작업을 실행했습니다. 이때쯤 비즈니스 계층이 계속 Web 프레임워크에 의존하는 것은 매우 어색해 보였습니다.
그래서 나는 Service를 분리하여 비즈니스와 데이터 접근 능력을 담당하게 하고, 서로 다른 진입점이 그것을 호출하게 했습니다.
듣기에는 이미 디커플링된 것 같죠? 현실이 또 한 방 날렸습니다.
한 번 CLI의 도움말 명령을 실행했는데, 출력된 것이 Web 프레임워크의 도움말이었습니다.
원인은 명령 모듈이 Service를 import하고, Service가 다시 최상위에서 Web 프레임워크의 Request 타입을 import했기 때문입니다. 그것은 원래 타입 주석일 뿐이었지만, 런타임에 전체 프레임워크를 끌어들여 명령줄 인자 파싱에 영향을 주었습니다.
수정은 복잡하지 않습니다: 순수 타입 의존성을 TYPE_CHECKING 아래로 옮기고, 명령 등록 단계는 가능한 한 가볍게 유지하며, 실제 실행 시에 필요한 모듈을 로드합니다.
하지만 이 작은 일로 나는 깨달았습니다. 아키텍처 다이어그램의 의존 화살표는 결국 모듈 import와 초기화 동작으로 구현되어야 한다는 것을. 아주 깔끔해 보이는 Service라도, 그것을 import하면 프레임워크를 끌어오고, 인자를 읽고, 외부 연결을 시작한다면, 다른 진입점에서 호출할 때 문제는 여전히 드러납니다.
나중에 나는 사용자 설정을 단순화하기 위해 일부 데이터 능력을 원격으로 옮기려 시도했습니다. 원래 ORM 객체를 가져오던 곳은 명확한 반환 구조를 소비하도록 바꿔야 했고; 진입점과 Graph에 흩어져 있던 데이터베이스 작업도 계속 Service로 모아야 했습니다.
나는 통합 분배 계층을 추가했습니다: 로컬 모드는 Service를 호출하고, 원격 모드는 해당 HTTP API를 호출합니다. 직렬화도 이 경계에서 처리하여, 열거형, 시간 객체, 선택적 매개변수의 변환이 곳곳에 흩어지는 것을 피했습니다.
예를 들어 기본값이 있는 조회 매개변수는 Python 함수에서 None을 전달하는 것이 자연스럽지만, HTTP query 인코딩에서는 직접 오류가 날 수 있습니다. 수정은 요청 경계에서 처리해야 하며, 동시에 0, False 같은 실제 의미가 있는 값을 보존해야 합니다; JSON 요청 본문의 명시적 null도 함께 삭제해서는 안 됩니다.
이것들은 복잡한 알고리즘이 아니지만, '로컬에서 호출 가능한 함수'가 신뢰할 수 있는 원격 인터페이스가 될 수 있는지를 결정합니다.
5. 사용자가 데이터베이스를 하나 덜 구성하면, 시스템은 책임을 한 세트 더 진다
CLI와 IM 진입점을 만든 것은 처음에는 독립 프론트엔드 개발량을 줄이고 사용자가 익숙한 곳에서 상호작용하게 하기 위해서였습니다.
하지만 설치 과정을 연결하면서, 나는 프론트엔드만 생략했을 뿐 사용자는 여전히 데이터베이스, 모델 설정, 봇 설정을 준비해야 한다는 것을 발견했습니다. 코드가 돌아간다고 해서 사용자가 기꺼이 사용하기까지는 아직 긴 길이 남아 있습니다.
따라서 나는 서버 측이 데이터베이스 접근을承接하게 하여 사용자가 직접 DB를 구축하는 부담을 줄이려 시도했습니다.
첫 번째 제약은 명확합니다: 편의를 위해 공유 데이터베이스의 연결 자격 증명을 클라이언트에 보낼 수는 없습니다. 일반 데이터 작업은 인증 API로承接할 수 있지만, 워크플로의 checkpoint는 데이터베이스 연결에 의존하며, HTTP 라우트를 추가했다고 해서 자동으로 원격 저장 능력을 얻는 것은 아닙니다.
당시 처리는 두 가지 동작을 유지하는 것이었습니다: 로컬 모드는 계속 PostgreSQL로 checkpoint를 영속화하고; 실험적 공유 모드는 프로세스 메모리로 전환했습니다.
대가도 명확합니다: 프로세스가 재시작되면 공유 모드의 이 단기 기억은 사라집니다.
나는 이 문제를 완전히 해결하지 않았고, 단지 클라이언트에 데이터베이스 연결을 노출하지 않는 실행 방식을 얻기 위해 한 단계 다운그레이드를 받아들였습니다. 이것이 checkpoint가 영원히 원격화될 수 없다는 뜻은 아니며, 단지 당시 그 분배 계층이 그것을 커버하지 못했고, 계속 추상화하는 비용이 그 라운드의 목표를 넘어섰다는 것입니다.
더 골치 아픈 문제는 뒤에 있었습니다.
일부 '데이터 동기화'로 보이는 Service는 내부에서 실제로 모델을 호출합니다. 그것을 서버 측으로 옮기면, 도대체 누구의 모델 설정을 사용해야 합니까? 사용자의 설정은 어떻게 전달합니까? 호출 비용은 누가 부담합니까?
원래 단일 머신에서는 데이터베이스, 모델 설정, 실행 환경이 모두 같은 곳에 있어서 이런 문제들이 쉽게 무시되었습니다. 네트워크를 넘으면每一项을 다시 답해야 합니다.
로그인 상태도 마찬가지입니다. 백그라운드 작업이 token 만료로 중단되는 것을 줄이기 위해, 나는 한때 만료 시간을 설정하지 않는 방식을 사용했습니다. 하지만 그것이 남기는 교체, 철회, 무효화 관리 문제는 여전히 존재하며, 메인 체인이 계속 실행된다고 해서 인증이 완전히 설계되었다고 말할 수는 없습니다.
결국 공유 모드의 일부 체인은 이미 연결되었지만, 나는 여전히 공개 설정 진입점을 숨겼습니다. 모델 설정 귀속과 서버 측 대행 실행의 경계가 깔끔하게 처리되지 않았다면, 사용자가 그것을 이미 준비된 옵션으로 여기게 해서는 안 됩니다.
이것은 제품 차원에서의 나의 전환점이기도 합니다: 사용 비용을 낮춘다는 것은 누군가 원래 사용자에게 넘겼던 복잡성을 떠맡아야 한다는 뜻입니다. 데이터베이스를 사용자가 구성하지 않아도 되면, 서버 측이 해당 권한, 설정, 실행 책임을 받아내야 합니다. 하나의 'Easy Mode'는 입력 상자를 몇 개 덜 보여주는 것과는 거리가 멉니다.

6. 한 번의 프롬프트 서비스 장애로 인해 실행 의존성을 다시 보게 되었다
또 한 번의 교훈은 모델 능력과 거의 관계가 없었습니다.
조정을 편하게 하기 위해 나는 프롬프트를 외부 플랫폼에 두고 런타임에 실시간으로 가져왔습니다. 프롬프트를 수정할 때 다시 배포할 필요가 없어 개발 경험이 정말 좋았습니다.
그런데 플랫폼 서비스가 장애를 일으켰습니다.
나는 로컬 백업도 보관하지 않았고, 읽기 실패에 대한 폴백도 설계하지 않아서, 프롬프트와 관련된 체인이 한꺼번에 모두 죽었습니다. 외부 서비스는 약 이틀 후에 복구되었지만, 이틀이면 나에게 깨닫게 하기에 충분했습니다: 나는 개발 편의 도구를 런타임의 하드 의존성으로 놓아버린 것입니다.
이 일이 나에게 준 교훈은 아주 구체적입니다. 프롬프트는 비록 한 단락의 텍스트이지만 시스템에서 실제 실행 로직을 담당합니다; 그것의 버전, 백업, 가용성은 모두 진지하게 다루어야 합니다. 그것을 원격에서 관리한다고 해서 이러한 책임이 사라지는 것은 아닙니다.
이후 개발 과정에서 저는 반복적으로 등장하는 협업 요구 사항을 Skill로 정착시키기 시작했습니다. 변경 후 품질 검사, 변경 사항 기록, Graph 문서 동기화, 그리고 교정 내용을 규칙에 다시 반영하는 일입니다.
이러한 규정은 테스트를 대체할 수 없고, Agent가 매번 올바르게 실행된다는 것도 보장하지 못합니다. 하지만 적어도 같은 종류의 누락이 다시 발생했을 때, 저는 단지 다시 한 번 상기시키는 것에 그치지 않고 계속 소비되는 규칙을 수정할 기회를 갖게 됩니다.
마지막으로
돌이켜 보면, 이번 재작성은 어느 날 모든 문제를 깨닫고 새로운 아키텍처 그림을 그려서 한 번에 완성한 것이 아니었습니다.
저는 먼저 checkpoint를 오해했고, 그다음 상태를 다시 설계했습니다. 먼저 세밀한 입력을 추구했고, 다시 하류에서 실제로 필요한 의미로 돌아갔습니다. 먼저 비즈니스 계층을 분리하고 불필요한 진입점을 삭제했으며, 나중에는 새로운 배포 방식을 위해 HTTP 서비스를 다시 보충했습니다. 새로운 문제가 끊임없이 나타나고, 앞서 내린 선택도 다시 검토됩니다.
저는 더 이상 "애초에 프레임워크를 잘못 선택한 게 아닐까"에 특별히 얽매이지 않습니다. 저를 실제로 멀리 돌아가게 한 것은 몇 가지 더 기초적인 경계를 명확히 하지 못한 점입니다. 무엇을 영속화해야 하는지, 무엇이 모델로 들어가야 하는지, 어떤 파라미터를 프로그램이 결정하는지, 그리고 한 가지 기능이 실행 위치를 바꾼 뒤에 어떤 책임을 함께 가져가는지입니다.
이제 새로운 기능을 작성하기 시작하면, 저는 예전보다 조금 더 시간을 들여 이런 질문들을 던집니다. 그것들이 반드시 처음부터 올바르게 해 주지는 못하지만, 겉보기에는 이미 완성된 것처럼 보이면서도 다른 상황에서는 다시 뒤집어야 하는 코드를 덜 작성하게 해 줍니다.
이번 재작성에서 제가 가장 남기고 싶은 성과는, 아마도 앞으로도 계속 제가 코드를 작성하는 방식에 영향을 줄 이러한 질문들일 것입니다.