LangGraph와 클린 아키텍처를 결합한 유지보수 가능한 AI 에이전트 템플릿

실용적 조언

에이전트의 상태 리듀서와 라우팅 로직을 테스트할 때는 실제 LLM 대신 Mock 객체를 주입하여 비용을 절감하라.
긴 실행 시간이 필요한 에이전트 작업은 Celery와 같은 태스크 큐를 사용하여 백그라운드에서 처리하라.
도구 연동 시 MCP를 활용하여 에이전트 로직과 도구 구현 간의 결합도를 낮추라.

섹션별 상세

AI 에이전트의 핵심 비즈니스 로직을 순수 파이썬 코드로 작성하고 LangGraph나 LLM, 데이터베이스를 교체 가능한 인프라 계층으로 처리했다. 이는 외부 라이브러리나 API의 변경이 핵심 로직에 영향을 주지 않도록 격리하여 시스템의 안정성을 높이는 구조이다. 의존성 주입을 통해 LLM을 추상화함으로써 실제 API 비용을 지불하지 않고도 그래프의 라우팅 로직과 상태 리듀서를 단위 테스트할 수 있는 환경을 구축했다.

FastAPI와 Celery를 조합하여 비동기 작업 처리를 구현했다. FastAPI가 HTTP 요청 레이어를 담당하고, Celery가 시간이 오래 걸리는 에이전트 루프를 백그라운드 워커로 넘겨 처리함으로써 사용자 경험을 개선했다. 이러한 구조는 특히 인간의 개입이 필요한 Human-in-the-loop 워크플로우에서 긴 대기 시간을 효율적으로 관리하는 데 적합하다.

Model Context Protocol(MCP) 게이트웨이를 내장하여 도구 및 파일 시스템 접근을 표준화했다. MCP를 통해 에이전트와 도구 간의 결합도를 낮추고 표준화된 방식으로 외부 리소스에 접근할 수 있도록 설계했다. 이는 에이전트가 사용하는 도구가 늘어나더라도 일관된 인터페이스를 유지할 수 있게 해준다.

비결정적인 AI 컴포넌트를 감싸는 주변 시스템은 고도로 결정적이어야 한다는 철학을 바탕으로 프로덕션 환경을 구성했다. Docker Compose, Alembic 마이그레이션, 엄격한 타입 체크 및 pre-commit 훅을 포함하여 단순한 프로토타입을 넘어선 실제 운영 가능한 수준의 개발 환경을 제공한다. 이를 통해 AI 에이전트 개발을 '빠른 스크립트 작성'에서 '견고한 시스템 구축' 단계로 격상시키고자 했다.

용어 해설

클린 아키텍처(Clean Architecture): — 소프트웨어의 비즈니스 로직을 외부 인프라(DB, UI, 프레임워크)와 분리하여 결합도를 낮추는 설계 원칙이다. AI 에이전트 개발 시 LLM API나 특정 라이브러리에 종속되지 않고 핵심 로직을 독립적으로 유지하고 테스트할 수 있게 한다.
모델 컨텍스트 프로토콜(Model Context Protocol): — AI 모델이 외부 도구, 데이터 소스 및 파일 시스템에 접근할 때 사용하는 표준화된 통신 규약이다. 도구 접근 방식을 표준화하여 에이전트와 외부 도구 간의 결합을 분리하고 재사용성을 높이는 역할을 한다.
의존성 주입(Dependency Injection): — 객체가 필요로 하는 의존 객체를 직접 생성하지 않고 외부에서 주입받는 디자인 패턴이다. LLM 인터페이스를 추상화하여 주입함으로써 실제 API 호출 없이도 그래프 라우팅이나 상태 변화를 단위 테스트할 수 있게 한다.
상태 관리(State Management): — 에이전트가 대화 흐름이나 작업 단계에서 발생하는 데이터를 유지하고 업데이트하는 프로세스이다. LangGraph와 같은 도구를 통해 복잡한 에이전트 루프 내에서 데이터의 일관성을 보장하고 비결정적인 AI 동작을 제어한다.

언급된 도구

LangGraph추천

상태 기반 에이전트 오케스트레이션

FastAPI추천

HTTP 레이어 및 API 핸들링

Celery추천

백그라운드 워커 및 장시간 작업 처리

MCP추천

표준화된 도구 및 파일 시스템 접근 프로토콜

언급된 리소스

GitHublanggraph-agent-clean-architecture GitHub