NL2SQL 도구

개요

이 도구는 자연어를 SQL 쿼리로 변환하는 데 사용됩니다. 에이전트에 전달되면 쿼리를 생성하고 이를 사용하여 데이터베이스와 상호작용합니다. 이를 통해 에이전트가 데이터베이스에 접근하여 목표에 따라 정보를 가져오고, 해당 정보를 사용해 응답, 보고서 또는 기타 출력물을 생성하는 다양한 워크플로우가 가능해집니다. 또한 에이전트가 자신의 목표에 맞춰 데이터베이스를 업데이트할 수 있는 기능도 제공합니다. 주의: 도구는 기본적으로 읽기 전용(SELECT/SHOW/DESCRIBE/EXPLAIN만 허용)으로 동작합니다. 쓰기 작업을 수행하려면 allow_dml=True 매개변수 또는 CREWAI_NL2SQL_ALLOW_DML=true 환경 변수가 필요합니다. 쓰기 접근이 활성화된 경우, 가능하면 권한이 제한된 데이터베이스 사용자나 읽기 복제본을 사용하십시오.

읽기 전용 모드 및 DML 구성

NL2SQLTool은 기본적으로 읽기 전용 모드로 동작합니다. 추가 구성 없이 허용되는 구문 유형은 다음과 같습니다:

SELECT
SHOW
DESCRIBE
EXPLAIN

DML을 명시적으로 활성화하지 않으면 쓰기 작업(INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE 등)을 실행하려고 할 때 오류가 발생합니다. 읽기 전용 모드에서는 세미콜론이 포함된 다중 구문 쿼리(예: SELECT 1; DROP TABLE users)도 인젝션 공격을 방지하기 위해 차단됩니다.

쓰기 작업 활성화

DML(데이터 조작 언어)을 활성화하는 방법은 두 가지입니다: 옵션 1 — 생성자 매개변수:

from crewai_tools import NL2SQLTool

nl2sql = NL2SQLTool(
    db_uri="postgresql://example@localhost:5432/test_db",
    allow_dml=True,
)

옵션 2 — 환경 변수:

CREWAI_NL2SQL_ALLOW_DML=true

from crewai_tools import NL2SQLTool

# 환경 변수를 통해 DML 활성화
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")

사용 예시

읽기 전용(기본값) — 분석 및 보고 워크로드에 안전:

from crewai_tools import NL2SQLTool

# SELECT/SHOW/DESCRIBE/EXPLAIN만 허용
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")

DML 활성화 — 쓰기 워크로드에 필요:

from crewai_tools import NL2SQLTool

# INSERT, UPDATE, DELETE, DROP 등이 허용됨
nl2sql = NL2SQLTool(
    db_uri="postgresql://example@localhost:5432/test_db",
    allow_dml=True,
)

DML을 활성화하면 에이전트가 데이터를 수정하거나 삭제할 수 있습니다. 사용 사례에서 명시적으로 쓰기 접근이 필요한 경우에만 활성화하고, 데이터베이스 자격 증명이 최소 필요 권한으로 제한되어 있는지 확인하십시오.

요구 사항

SqlAlchemy
모든 DB 호환 라이브러리(예: psycopg2, mysql-connector-python)

설치

crewai_tools 패키지 설치

pip install 'crewai[tools]'

사용법

NL2SQLTool을 사용하려면 데이터베이스 URI를 도구에 전달해야 합니다. URI는 dialect+driver://username:password@host:port/database 형식이어야 합니다.

Code

from crewai_tools import NL2SQLTool

# psycopg2 was installed to run this example with PostgreSQL
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")

@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config["researcher"],
        allow_delegation=False,
        tools=[nl2sql]
    )

예시

주요 작업 목표는 다음과 같았습니다: “각 도시에 대해 월별 평균, 최대, 최소 매출을 조회하되, 사용자 수가 1명 초과인 도시만 포함하세요. 또한 각 도시의 사용자 수를 세고, 평균 월 매출을 기준으로 내림차순 정렬하십시오.” 그래서 에이전트는 DB에서 정보를 얻으려고 시도했고, 처음 시도는 잘못되었으므로 에이전트가 다시 시도하여 올바른 정보를 얻은 후 다음 에이전트로 전달합니다. 두 번째 작업 목표는 다음과 같았습니다: “데이터를 검토하고 상세한 보고서를 작성한 다음, 제공된 데이터를 기반으로 필드를 갖는 테이블을 데이터베이스에 생성하세요. 각 도시에 대해 월별 평균, 최대, 최소 매출 정보를 포함하되, 사용자 수가 1명 초과인 도시만 포함시키세요. 또한 각 도시의 사용자 수를 세고, 평균 월 매출을 기준으로 내림차순 정렬하십시오.” 이제 상황이 흥미로워집니다. 에이전트는 테이블을 생성할 SQL 쿼리뿐만 아니라 데이터를 테이블에 삽입하는 쿼리도 생성합니다. 그리고 마지막에는 데이터베이스에 있던 것과 정확히 일치하는 최종 보고서도 반환합니다. 이것은 NL2SQLTool이 데이터베이스와 상호작용하고, 데이터베이스의 데이터를 기반으로 보고서를 생성하는 데 어떻게 사용될 수 있는지에 대한 간단한 예시입니다. 이 도구는 에이전트의 논리와 데이터베이스와 상호작용하는 방식에 대해 무한한 가능성을 제공합니다.

 DB -> Agent -> ... -> Agent -> DB

시작 안내

가이드

핵심 개념

MCP 통합

도구 (Tools)

Observability

학습

Telemetry

개요

읽기 전용 모드 및 DML 구성

쓰기 작업 활성화

사용 예시

요구 사항

설치

사용법

예시

​개요

​읽기 전용 모드 및 DML 구성

​쓰기 작업 활성화

​사용 예시

​요구 사항

​설치

​사용법

​예시

개요

읽기 전용 모드 및 DML 구성

쓰기 작업 활성화

사용 예시

요구 사항

설치

사용법

예시