커스텀 SQL 에이전트 만들기
커스텀 SQL 에이전트 만들기 (Build a custom SQL agent)
이 튜토리얼에서는 LangGraph로 SQL 데이터베이스에 대한 질문에 답하는 커스텀 에이전트를 만들어요. LangChain은 LangGraph 프리미티브로 구현된 내장 에이전트를 제공하고, 더 깊은 커스터마이징이 필요하면 에이전트를 LangGraph에서 직접 구현할 수 있어요. 이 가이드는 SQL 에이전트의 예시 구현을 보여줘요. 상위 수준의 LangChain 추상화로 SQL 에이전트를 만드는 실용적인 소개는 "higher-level LangChain abstractions로 SQL 에이전트 구축" 문서를 참고하세요. 내장 에이전트(prebuilt agent)는 시스템 프롬프트로 동작을 제약했다면, 여기서는 전용 노드를 둬서 툴 호출과 프롬프트를 더 세밀하게 제어해요.
출처: 공식문서
개념
- SQL 데이터베이스에서 읽기 위한 툴(Tools)
- LangGraph Graph API — 상태, 노드, 엣지, 조건부 엣지
- Human-in-the-loop(사람 개입) 프로세스
설정
LangSmith를 설정해서 체인/에이전트 내부를 살펴볼 수 있게 하고 관련 환경 변수를 지정해요.
1. LLM 선택
툴 호출을 지원하는 모델을 선택해요: OpenAI, Anthropic, Azure, Google Gemini, AWS Bedrock, HuggingFace, OpenRouter 등. 예제 출력은 OpenAI로 생성된 것이에요.
2. 데이터베이스 구성
이 튜토리얼에서는 SQLite 데이터베이스를 만들어요. Python 내장 sqlite3 모듈로 상호작용하고, 디지털 미디어 상점을 나타내는 샘플 데이터베이스 chinook(Chinook.db)을 공개 GCS 버킷에서 로드해요.
3. 데이터베이스 상호작용 툴 추가
langchain.tools의 @tool 데코레이터로 데이터베이스 툴을 얇은 래퍼로 구현할 수 있어요.
4. 애플리케이션 단계 정의
다음 단계 전용 노드를 구성해요:
- DB 테이블 나열
- "get schema" 툴 호출
- 쿼리 생성
- 쿼리 검사
전용 노드로 나누면 (1) 필요할 때 툴 호출을 강제할 수 있고, (2) 각 단계와 연결된 프롬프트를 커스터마이징할 수 있어요.
5. 에이전트 구현
Graph API로 이 단계들을 워크플로로 조립해요. 쿼리 생성 단계에 조건부 엣지를 정의해서, 쿼리가 생성되면 쿼리 검사기로 라우팅하고 툴 호출이 없으면(즉 LLM이 응답을 전달했으면) 끝나도록 해요.
6. Human-in-the-loop 리뷰
에이전트의 SQL 쿼리를 실행 전에 검토하는 게 바람직해요. 여기서는 LangGraph의 interrupt 함수와 영속성 계층을 활용해 SQL 쿼리 실행 전에 실행을 멈추고 사람의 검토를 기다려요. 승인·인자 편집·사용자 피드백 입력을 허용할 수 있어요. Command로 툴 호출을 승인하거나 편집할 수 있고, 실행을 일시 중지·재개하려면 체크포인터가 필요하다는 점을 기억하세요.
더 알아보기 (Learn more)
- LangSmith로 LangGraph 애플리케이션(그래프 평가하기)을 평가하는 법 — SQL 에이전트 포함.
- Human-in-the-loop 가이드와 Graph API 문서