데이터 분석 에이전트 개발기: 컨텍스트 엔지니어링 설계 원칙

LLM 에이전트의 자율성이 높아지면서, 모델이 목표와 진행 상황을 정확히 파악하도록 정보를 선별하고 구성하는 컨텍스트 엔지니어링이 중요해졌습니다. 데이터 분석 에이전트 개발 경험을 바탕으로 시스템 프롬프트, 도구 명세서, 메시지 배열의 세 가지 요소를 중심으로 컨텍스트를 설계한 방법을 살펴봅니다.

시스템 프롬프트와 도구 명세서의 역할 분리

시스템 프롬프트에는 에이전트의 역할, 안전 규칙, 판단 기준, 그리고 여러 도구에 공통으로 적용되는 사용 원칙을 작성합니다. 반면, 개별 도구의 상세한 사용 조건, 입력값의 의미, 결과 전달 방식은 도구 명세서에 구체적으로 기술합니다. Anthropic의 가이드에 따라 도구 설명은 매우 상세해야 하며, Claude Code 사례에서는 도구 명세서 분량이 시스템 프롬프트의 약 4배인 15k 토큰에 달했습니다.

도구 설계 시에는 관련 기능을 하나의 도구로 묶어 인터페이스를 단순화하는 '깊은 모듈' 개념을 적용할 수 있습니다. 예를 들어 SQL 노트의 생성과 수정 기능을 upsert_note 하나의 도구로 통합하거나, SQL 작성부터 실행 및 오류 수정까지를 서브에이전트로 처리하도록 구성하여 도구 선택의 복잡성을 줄입니다.

점진적 발견과 서브에이전트 활용

에이전트가 필요한 정보를 단계적으로 찾아내는 점진적 발견(Progressive Disclosure) 방식을 적용했습니다. 초기에는 별도의 탐색 에이전트를 사용했으나, 메인 에이전트가 접근 가능한 전체 테이블 목록을 시스템 프롬프트에 미리 인지하고 필요 시 상세 스키마를 조회하도록 변경했습니다. 이를 통해 불필요한 탐색 턴을 줄이고, 데이터 부재 상황을 더 빠르게 파악할 수 있었습니다.

또한, SQL 작성과 실행 중 발생하는 오류 메시지나 실패 기록이 메인 컨텍스트에 누적되는 문제를 해결하기 위해 서브에이전트를 도입했습니다. 서브에이전트는 별도의 컨텍스트에서 SQL 생성, 실행, 오류 수정을 전담하며, 메인 에이전트에는 최종 결과만 전달합니다. 이는 대화 기록이 오염되는 것을 방지하고 메인 에이전트의 판단 정확도를 유지하는 데 효과적입니다.