이 문서에서는 Gemini CLI와 MCP 도구 상자를 사용하여 에이전트 컨텍스트 파일을 빌드하는 방법을 설명합니다. 이러한 파일에는 자연어에서 SQL 쿼리를 생성하기 위한 컨텍스트를 제공하는 템플릿과 패싯이 포함되어 있습니다. DB 컨텍스트 보강 MCP 서버도 사용합니다.
데이터 에이전트에 대해 알아보려면 데이터 에이전트 개요를 참고하세요.에이전트 컨텍스트를 빌드하려면 다음 대략적인 단계를 따르세요.
- 개발 환경 준비
- 타겟팅된 템플릿 생성
- 타겟 패싯 생성
- 선택사항입니다. 대량 템플릿 생성
시작하기 전에
에이전트를 만들기 전에 다음 기본 요건을 완료하세요.
Spanner 인스턴스 준비
- Spanner 인스턴스를 사용할 수 있는지 확인합니다. 자세한 내용은 인스턴스 만들기를 참고하세요.
- 최종 사용자가 액세스하려는 데이터와 스키마로 데이터베이스를 채웁니다.
필수 역할 및 권한
- 클러스터에 IAM 사용자 또는 서비스 계정을 추가합니다. 자세한 내용은 IAM 역할 적용을 참고하세요.
- 프로젝트 수준에서 IAM 사용자에게
spanner.databaseReader역할을 부여합니다. 자세한 내용은 프로젝트의 IAM 정책 바인딩 추가를 참고하세요. - 필요한 데이터베이스에 대해 프로젝트 수준에서 IAM 사용자에게 역할과 권한을 부여합니다.
개발 환경 준비
로컬 개발 환경 또는 IDE에서 에이전트 컨텍스트 파일을 빌드할 수 있습니다. 환경을 준비하려면 다음 단계를 따르세요.
- Gemini CLI 설치
- MCP 도구 상자 설치 및 설정
- DB 컨텍스트 보강 MCP 서버 설치 및 설정
Gemini CLI 설치
Gemini CLI를 설치하려면 Gemini CLI 시작하기를 참고하세요. MCP 도구 상자 및 DB 컨텍스트 보강 MCP 서버를 설치하는 데도 사용되는 별도의 디렉터리에 Gemini CLI를 설치해야 합니다.
MCP 도구 상자 설치 및 설정
Gemini CLI를 설치한 동일한 디렉터리에서 MCP 도구 상자 Gemini CLI 확장 프로그램을 설치합니다.
gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox데이터베이스 연결을 구성하기 위해 MCP 도구 상자를 설치한 디렉터리에
tools.yaml구성 파일을 만듭니다.sources: my-spanner-source: kind: spanner project: PROJECT_ID instance: INSTANCE_ID database: DATABASE_ID다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.INSTANCE_ID: Spanner 인스턴스의 ID입니다.DATABASE_ID: 연결할 데이터베이스의 이름입니다.
tools.yaml파일이 올바르게 구성되었는지 확인합니다../toolbox --tools-file "tools.yaml"
DB 컨텍스트 보강 MCP 서버 설치
DB 컨텍스트 보강 MCP 서버는 데이터베이스 스키마에서 구조화된 NL2SQL 템플릿을 생성하는 안내형 대화형 워크플로를 제공합니다. 데이터베이스 연결에는 MCP 도구 상자 확장 프로그램이 사용됩니다. DB 컨텍스트 보강 MCP 서버 설치에 대한 자세한 내용은 DB 컨텍스트 보강 MCP 서버를 참고하세요.
DB 컨텍스트 보강 MCP 서버를 설치하려면 다음을 실행하세요.
Gemini CLI를 설치한 디렉터리에서
uvPython 패키지 설치 프로그램을 설치합니다.pip install --user pipx pipx ensurepath pipx install uvDB 컨텍스트 보강 MCP 서버를 설치합니다.
gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
서버는 생성을 위해 Gemini API를 사용합니다. API 키를 환경 변수로 내보내야 합니다. API 키를 찾는 방법에 대한 자세한 내용은 Gemini API 키 사용을 참고하세요.
Gemini API 키를 내보내려면 다음 명령어를 실행합니다.
export GEMINI_API_KEY="YOUR_API_KEY"YOUR_API_KEY를 Gemini API 키로 바꿉니다.
타겟팅된 템플릿 생성
특정 질문-대답 쌍을 에이전트 컨텍스트에 질문 템플릿으로 추가하려면 /generate_targeted_templates 명령어를 사용하면 됩니다. 템플릿에 대한 자세한 내용은 데이터 에이전트 개요를 참고하세요.
에이전트 컨텍스트에 쿼리 템플릿을 추가하려면 다음 단계를 따르세요.
Gemini CLI를 설치한 동일한 디렉터리에서 Gemini를 시작합니다.
geminiGemini CLI 인증 설정을 완료합니다.
MCP 도구 상자와 데이터베이스 보강 확장 프로그램을 사용할 준비가 되었는지 확인합니다.
/mcp list/generate_targeted_templates명령어를 실행합니다./generate_targeted_templates쿼리 템플릿에 추가할 자연어 쿼리를 입력합니다.
쿼리 템플릿에 해당하는 SQL 쿼리를 입력합니다.
생성된 쿼리 템플릿을 검토합니다. 쿼리 템플릿을 에이전트 컨텍스트 파일로 저장하거나 기존 컨텍스트 파일에 추가할 수 있습니다.
my-cluster-psc-primary_postgres_templates_20251104111122.json와 유사한 에이전트 컨텍스트 파일이 명령어를 실행한 디렉터리에 저장됩니다.
컨텍스트 파일 및 쿼리 템플릿에 관한 자세한 내용은 에이전트 컨텍스트를 참고하세요.
타겟 패싯 생성
특정 질문-대답 쌍을 에이전트 컨텍스트 파일에 패싯으로 추가하려면 /generate_targeted_fragments 명령어를 사용하면 됩니다. 패싯에 대한 자세한 내용은 데이터 에이전트 개요를 참고하세요.
에이전트 컨텍스트에 패싯을 추가하려면 다음 단계를 따르세요.
/generate_targeted_fragments명령어를 실행합니다./generate_targeted_fragments쿼리 템플릿에 추가할 자연어 쿼리를 입력합니다.
쿼리 템플릿에 해당하는 SQL 쿼리를 입력합니다.
생성된 패싯을 검토합니다. 패싯을 에이전트 컨텍스트 파일에 저장하거나 기존 컨텍스트 파일에 추가할 수 있습니다.
my-cluster-psc-primary_postgres_templates_20251104111122.json와 유사한 에이전트 컨텍스트 파일이 명령어를 실행한 디렉터리에 저장됩니다.
컨텍스트 파일 및 패싯에 관한 자세한 내용은 에이전트 컨텍스트를 참고하세요.
선택사항: 대량 템플릿 생성
데이터베이스 스키마와 데이터를 기반으로 에이전트 컨텍스트 파일을 자동 생성하려면 /generate_bulk_templates 명령어를 사용하면 됩니다.
대량 템플릿을 자동 생성하려면 다음 단계를 따르세요.
/generate_bulk_templates명령어를 실행합니다./generate_bulk_templates데이터베이스 스키마를 기반으로 템플릿 기반 SQL 생성에서는 데이터베이스 정보를 확인하고 데이터베이스 스키마에 액세스할 권한을 부여하는 것과 관련된 일련의 질문을 안내합니다.
생성된 쿼리 템플릿을 검토합니다. 템플릿을 승인하거나 수정하려는 쿼리 쌍을 업데이트할 수 있습니다.
쿼리 템플릿에 추가할 자연어 쿼리를 입력합니다.
쿼리 템플릿에 해당하는 SQL 쿼리를 입력합니다.
생성된 쿼리 템플릿을 검토합니다. 쿼리 템플릿을 에이전트 컨텍스트 파일로 저장하거나 기존 컨텍스트 파일에 추가할 수 있습니다.
쿼리 템플릿을 승인한 후 새 템플릿 파일을 만들거나 기존 템플릿 파일에 쿼리 쌍을 추가할 수 있습니다. 쿼리 템플릿이 로컬 디렉터리에 JSON 파일로 저장됩니다.
my-cluster-psc-primary_postgres_templates_20251104111122.json와 유사한 에이전트 컨텍스트 파일이 명령어를 실행한 디렉터리에 저장됩니다.
에이전트 컨텍스트 파일에 관한 자세한 내용은 에이전트 컨텍스트를 참고하세요.
다음 단계
- 데이터 에이전트에 대해 자세히 알아보세요.
- Spanner Studio에서 데이터 에이전트를 만들거나 삭제하는 방법을 알아보세요.
- 데이터 에이전트를 검사하고 호출하는 방법을 알아봅니다.