Overview
이 튜토리얼에서는 LangChain agents를 사용하여 SQL 데이터베이스에 대한 질문에 답변할 수 있는 agent를 만드는 방법을 배웁니다. 높은 수준에서 agent는 다음을 수행합니다:1
데이터베이스에서 사용 가능한 테이블과 스키마 가져오기
2
질문과 관련된 테이블 결정하기
3
관련 테이블의 스키마 가져오기
4
질문과 스키마 정보를 기반으로 쿼리 생성하기
5
LLM을 사용하여 일반적인 실수가 있는지 쿼리 재확인하기
6
쿼리를 실행하고 결과 반환하기
7
쿼리가 성공할 때까지 데이터베이스 엔진에서 발생한 오류 수정하기
8
결과를 기반으로 응답 작성하기
SQL 데이터베이스의 Q&A 시스템을 구축하려면 모델이 생성한 SQL 쿼리를 실행해야 합니다. 이를 수행하는 데는 본질적인 위험이 있습니다. 데이터베이스 연결 권한이 항상 agent의 필요에 따라 가능한 한 좁게 범위가 지정되어 있는지 확인하세요. 이렇게 하면 모델 기반 시스템 구축의 위험을 완화할 수 있지만 완전히 제거할 수는 없습니다.
Concepts
다음 개념을 다룰 것입니다:- SQL 데이터베이스에서 읽기 위한 Tools
- LangChain agents
- Human-in-the-loop 프로세스
Setup
Installation
LangSmith
chain 또는 agent 내부에서 무슨 일이 일어나고 있는지 검사하려면 LangSmith를 설정하세요. 그런 다음 다음 환경 변수를 설정하세요:1. LLM 선택하기
tool-calling을 지원하는 모델을 선택하세요:- OpenAI
- Anthropic
- Azure
- Google Gemini
- AWS Bedrock
아래 예제에 표시된 출력은 OpenAI를 사용했습니다.
2. 데이터베이스 구성하기
이 튜토리얼에서는 SQLite database를 생성할 것입니다. SQLite는 설정하고 사용하기 쉬운 경량 데이터베이스입니다. 디지털 미디어 스토어를 나타내는 샘플 데이터베이스인chinook 데이터베이스를 로드할 것입니다.
편의를 위해 공개 GCS 버킷에 데이터베이스(Chinook.db)를 호스팅했습니다.
langchain_community 패키지에서 사용 가능한 편리한 SQL 데이터베이스 wrapper를 사용할 것입니다. wrapper는 SQL 쿼리를 실행하고 결과를 가져오는 간단한 인터페이스를 제공합니다:
3. 데이터베이스 상호 작용을 위한 tool 추가하기
데이터베이스와 상호 작용하기 위해langchain_community 패키지에서 사용 가능한 SQLDatabase wrapper를 사용하세요. wrapper는 SQL 쿼리를 실행하고 결과를 가져오는 간단한 인터페이스를 제공합니다:
5. create_agent 사용하기
create_agent를 사용하여 최소한의 코드로 ReAct agent를 구축하세요. agent는 요청을 해석하고 SQL 명령을 생성하며, tool이 이를 실행합니다. 명령에 오류가 있으면 오류 메시지가 모델로 반환됩니다. 그러면 모델은 원래 요청과 새 오류 메시지를 검토하고 새 명령을 생성할 수 있습니다. 이는 LLM이 명령을 성공적으로 생성하거나 종료 횟수에 도달할 때까지 계속될 수 있습니다. 이 경우 오류 메시지와 같은 피드백을 모델에 제공하는 패턴은 매우 강력합니다.
동작을 사용자 정의하기 위해 설명적인 system prompt로 agent를 초기화하세요:
6. Agent 실행하기
샘플 쿼리에서 agent를 실행하고 동작을 관찰하세요:수행된 단계, 호출된 tool, LLM이 본 prompt 등을 포함하여 위 실행의 모든 측면을 LangSmith trace에서 검사할 수 있습니다.
(선택 사항) Studio 사용하기
Studio는 “클라이언트 측” 루프와 메모리를 제공하므로 이를 채팅 인터페이스로 실행하고 데이터베이스를 쿼리할 수 있습니다. “데이터베이스의 스키마를 알려주세요” 또는 “상위 5명의 고객에 대한 송장을 보여주세요”와 같은 질문을 할 수 있습니다. 생성된 SQL 명령과 결과 출력을 볼 수 있습니다. 시작하는 방법에 대한 세부 정보는 아래에 있습니다.Studio에서 agent 실행하기
Studio에서 agent 실행하기
이전에 언급한 패키지 외에도 다음이 필요합니다:실행할 디렉토리에 다음 내용이 포함된
langgraph.json 파일이 필요합니다:sql_agent.py 파일을 생성하고 다음을 삽입하세요:6. Human-in-the-loop 검토 구현하기
의도하지 않은 작업이나 비효율성을 위해 agent의 SQL 쿼리를 실행하기 전에 확인하는 것이 신중할 수 있습니다. LangChain agent는 agent tool 호출에 대한 감독을 추가하기 위한 내장 human-in-the-loop middleware 지원 기능을 제공합니다.sql_db_query tool 호출 시 사람의 검토를 위해 일시 중지하도록 agent를 구성해 보겠습니다:
실행을 일시 중지하고 재개할 수 있도록 agent에 checkpointer를 추가했습니다. 이에 대한 세부 정보와 사용 가능한 middleware 구성은 human-in-the-loop guide를 참조하세요.
sql_db_query tool을 실행하기 전에 검토를 위해 일시 중지됩니다:
Next steps
더 깊은 사용자 정의를 위해 LangGraph primitive를 사용하여 SQL agent를 직접 구현하는 이 튜토리얼을 확인하세요.Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.