Elasticsearch용 Gemini CLI 확장 프로그램(도구 및 기술 포함)

Elasticsearch와 Elastic Agent Builder의 모든 기능을 AI 개발 워크플로우에 직접 통합할 수 있는 Google Gemini CLI용 Elastic 확장 기능을 출시합니다. 이 확장 프로그램은 Elasticsearch와 상호 작용하기 위한 최근 개발된 몇 가지 에이전트 스킬도 제공합니다.

확장 프로그램은 여기에서 오픈 소스 프로젝트로 제공됩니다.

Gemini CLI 소개 및 설치 방법

Gemini CLI는 Google의 Gemini 모델을 명령줄로 직접 가져오는 오픈 소스 AI 에이전트입니다. 개발자가 터미널을 통해 AI와 상호 작용하여 코드 생성, 파일 편집, 셸 명령 실행, 웹 정보 검색 등의 작업을 수행할 수 있습니다.

Gemini CLI는 일반적인 채팅 인터페이스와 달리 로컬 개발 환경과 통합되어 프로젝트 컨텍스트를 이해하고, 파일을 수정하고, 빌드나 테스트를 실행하고, 워크플로우를 터미널 내에서 직접 자동화할 수 있습니다. 이러한 특징 덕분에 개발자, 사이트 신뢰성 엔지니어(SRE)뿐만 아니라 명령줄 워크플로우를 벗어나지 않고 AI 기반 코딩 및 자동화를 원하는 엔지니어에게 유용합니다.

Gemini CLI는 여러 패키지 관리자를 사용하여 설치할 수 있습니다. 가장 일반적인 방법은 npm을 사용하는 것입니다:

다른 설치 옵션을 알고 싶다면 공식 설치 페이지를 참조하세요.

설치 후, 다음 명령어로 CLI를 실행하세요.

그림 1과 같은 화면이 표시됩니다.

Elasticsearch를 구성합니다

Elasticsearch 인스턴스가 실행 중이어야 합니다. 모델 컨텍스트 프로토콜(MCP) 서버를 사용하려면 Kibana 9.3+ 버전이 설치되어 있어야 합니다. 아래 설명된 Elasticsearch 쿼리 언어(ES|QL) 스킬(esql)을 사용하려면 Kibana가 없어도 됩니다.

Elastic Cloud에서 무료 체험을 활성화하거나 start-local 스크립트를 사용해 로컬에 설치할 수 있습니다.

이 명령을 실행하면 컴퓨터에 Elasticsearch와 Kibana가 설치되고 Gemini CLI 설정에 사용할 API 키가 생성됩니다.

API 키는 이전 명령의 출력 결과로 표시되며 .env 파일로 elastic-start-local 폴더에 저장됩니다.

온프레미스 Elasticsearch를 사용 중인 경우(예: start-local 사용), Elastic Agent Builder를 MCP와 함께 사용하려면 대규모 언어 모델(LLM)을 연결해야 합니다. 이 문서 페이지를 읽으면 다양한 옵션을 파악할 수 있습니다.

Elastic Cloud(또는 서버리스)를 사용하는 경우 이미 사전 구축된 LLM 연결이 제공됩니다.

Elasticsearch 확장 프로그램 설치

Elasticsearch 확장 프로그램을 Gemini CLI에 설치하려면 다음 명령어를 사용하세요.

Gemini를 열고 다음 명령어를 실행하면 확장 프로그램이 성공적으로 설치되었는지 확인할 수 있습니다.

Elasticsearch 확장 프로그램을 사용할 수 있는지 확인할 수 있습니다.

MCP 통합을 사용하려면 Elasticsearch 9.3 이상 버전이 설치되어 있어야 합니다. Kibana에서 가져온 MCP 서버 URL이 필요합니다.

• 에이전트에서 MCP 서버 URL 가져오기 > 모든 도구 보기 > MCP 관리 > MCP 서버 URL 복사
• 표시되는 URL: https://your-kibana-instance/api/agent_builder/mcp

Elasticsearch 엔드포인트 URL이 필요합니다. 일반적으로 이것은 Kibana Elasticsearch 페이지 상단에 보고됩니다. start-local로 Elasticsearch를 실행 중인 경우, start-local .env 파일의 ES_LOCAL_URL 키에 이미 엔드포인트가 있습니다.

API 키도 필요합니다. Elasticsearch를 start-local로 실행 중인 경우, 이미 ES_LOCAL_API_KEY가 start-local.env 파일에 있습니다. 그렇지 않은 경우, 여기에 설명된 대로 Kibana 인터페이스를 사용하여 API 키를 생성할 수 있습니다.

• Kibana: Stack Management > Security > API 키 > API 키 생성
• API 키에 대해 읽기 권한만 설정하여 여기에 보고된 대로 feature_agentBuilder.read 권한을 활성화할 것을 권장합니다.
• 인코딩된 API 키 값을 복사합니다.

셸에서 필요한 환경 변수를 설정하세요.

예제 데이터 세트 설치하기

Kibana에서 제공되는 eCommerce orders 데이터 세트를 설치할 수 있습니다. 이 데이터 세트에는 kibana_sample_data_ecommerce라는 단일 인덱스가 포함되어 있으며 전자상거래 웹사이트의 4,675개 주문 정보를 담고 있습니다. 각 주문에는 다음과 같은 정보가 포함되어 있습니다.

• 고객 정보(이름, ID, 생년월일, 이메일 등)
• 주문 날짜
• 주문 ID
• 제품(가격, 수량, ID, 카테고리, 할인, 기타 정보를 포함한 전체 제품 목록)
• SKU.
• 총액(세전, 세후)
• 총 수량
• 지리 정보(도시, 국가, 대륙, 위치, 지역).

샘플 데이터를 설치하려면 Kibana의 통합 페이지를 열고(상단 검색창에서 '통합'을 검색) "Sample Data"를 설치하세요. 자세한 내용은 여기 설명서를 확인하세요.

이 글의 목표는 Gemini CLI를 설정해 Elasticsearch에 연결하고 kibana_sample_data_ecommerce 인덱스와 손쉽게 상호작용하는 방법을 보여주는 것입니다.

Elasticsearch MCP를 사용하는 방법

Gemini에서 다음 명령을 사용하여 연결을 확인할 수 있습니다:

그림 2와 같이 elastic-agent-builder가 활성화된 것을 확인할 수 있습니다.

Elasticsearch는 기본 도구 세트를 제공합니다. 여기에서 설명을 참조하세요.

이 도구로 Elasticsearch와 상호 작용하며 다음과 같은 질문을 할 수 있습니다.

• Give me the list of all the indexes available in Elasticsearch.
• How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

질문에 따라 Gemini는 하나 이상의 도구를 사용하여 답변을 시도합니다.

/elastic

Gemini CLI의 Elasticsearch 확장 프로그램에서 /elastic 명령어를 추가했습니다.

/help 명령을 실행하면 사용 가능한 모든 /elastic 옵션이 표시됩니다(그림 3).

이 명령어들은 elastic-agent-builder MCP 서버의 특정 도구를 직접 실행하고자 할 때 유용할 수 있습니다. 예를 들어 다음 명령어를 사용하면 kibana_sample_data_ecommerce의 매핑을 얻을 수 있습니다.

이러한 명령은 Gemini 모델에 의존하여 실행할 도구를 결정하는 대신, 특정 도구를 실행하는 바로가기 역할을 합니다.

Elasticsearch 스킬 사용 방법

이 확장 기능에는 ES|QL용 에이전트 기술과 Elasticsearch에서 사용할 수 있는 Elasticsearch 쿼리 언어가 함께 제공됩니다. Agent Skills는 Gemini CLI와 같은 AI 코딩 에이전트에 특정 작업에 대한 사용자 지정 지침을 제공하는 개방형 형식입니다. 점진적 공개라는 개념을 사용하여 초기 시스템 프롬프트에 스킬에 대한 간략한 설명만 추가합니다. 에이전트에게 Elasticsearch 쿼리와 같은 작업을 수행하도록 요청하면 에이전트는 해당 요청을 관련 스킬과 연결하고 자세한 지침을 동적으로 불러옵니다. 이는 토큰 예산을 관리하면서 AI에 필요한 컨텍스트를 정확하게 제공하는 효율적인 방법입니다.

esql 스킬은 Gemini CLI가 클러스터에 직접 ES|QL 쿼리를 작성하고 실행할 수 있도록 설계되었습니다. ES|QL은 데이터 탐색, 로그 분석 및 집계를 매우 직관적으로 수행할 수 있는 강력한 파이프 쿼리 언어입니다. 이 스킬을 활성화하면 ES|QL 구문을 찾아볼 필요가 없습니다. Gemini CLI에 데이터에 대한 자연어 질문을 입력하기만 하면, 에이전트가 나머지 작업을 처리합니다.

실행은 터미널에서 실행되는 간단한 curl 명령어를 사용하여 수행됩니다. 이것이 가능한 것은 Elasticsearch가 어떤 아키텍처에도 쉽게 통합할 수 있는 풍부한 REST API 세트를 제공하기 때문입니다.

esql 스킬 제공 내용:

• 인덱스 및 스키마 검색: 에이전트가 스킬의 기본 제공 도구를 사용하여 사용 가능한 인덱스를 나열하고 필드 매핑을 가져올 수 있습니다. 예를 들어 전자상거래 데이터세트에 대한 쿼리를 작성하기 전에 에이전트가 kibana_sample_data_ecommerce 스키마 검사를 실행해서 사용 가능한 필드(예: taxful_total_price 또는 category)를 파악할 수 있습니다.
• 원활한 자연어 번역: 이 스킬은 에이전트에 단순한 참조 매뉴얼을 넘어 사용자 의도를 해석할 수 있는 구체적인 가이드를 제공합니다. '서비스별 평균 응답 시간 표시'와 같은 자연어 요청을 입력하면 에이전트가 스킬에 내장된 패턴 매칭 기능을 사용하여 사용자가 입력한 내용을 올바른 ES|QL 집계, 필터 및 명령으로 즉시 변환합니다.
• 자체 수정: 만일 타입 불일치 또는 구문 오류로 인해 쿼리가 실패하면, 스킬은 생성된 쿼리와 정확한 Elasticsearch 오류 메시지를 반환하여 에이전트가 즉시 쿼리를 수정하고 사용자가 개입하지 않아도 다시 시도할 수 있게 됩니다.

esql 스킬은 elastic-agent-builder MCP 서버에서도 도구로 제공되므로 이 서버를 잠시 비활성화해야 합니다. 다음 명령어를 사용하여 비활성화할 수 있습니다.

그런 다음 Gemini CLI에 다음과 같은 프롬프트를 입력하기만 하면 됩니다.

에이전트가 수행하는 작업:

• esql 스킬의 필요성을 인식해야 합니다.
• kibana_sample_data_ecommerce 스키마를 확인하세요.
• FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5 등 ES|QL 쿼리를 구성합니다.
• Elasticsearch API에 대해 쿼리 작업을 실행하세요.
• 터미널에서 바로 최종 답을 제시합니다.

여기서는 이전 프롬프트에 대한 Gemini의 응답 사례를 보고했습니다.

Gemini 모델이 최종 응답을 도출하는 모든 단계를 보여주는 방식은 흥미로운 부분입니다. 여기에서 모델의 추론 과정에 대한 스킬의 영향력을 확실하게 확인할 수 있습니다. 모델이 스킬을 사용하거나 셸 명령을 실행해야 한다고 처음 인식할 때, 휴먼 인 더 루프 방식을 사용하여 권한을 요청합니다.

esql 스킬은 스키마 발견, 쿼리 생성 및 실행과 같은 복잡한 작업을 처리함으로써 답을 얻는 과정의 메커니즘이 아닌 답 자체에만 집중할 수 있도록 도와줍니다. 필요한 데이터를 제대로 된 형식으로 터미널에서 바로 얻을 수 있습니다. 단 한 줄의 구문도 작성하거나 다른 애플리케이션으로 컨텍스트를 전환할 필요도 없습니다.

결론

이 글에서는 최근에 출시한 Gemini CLI용 Elasticsearch 확장 기능을 소개했습니다. 이 확장 프로그램을 사용하면 Gemini와 Elastic Agent Builder에서 제공하는 Elasticsearch MCP 서버(버전 9.3.0부터 사용 가능)를 이용하여 Elasticsearch 인스턴스와 상호 작용할 수 있습니다. /elastic 명령어도 사용할 수 있습니다.

더불어, 이 확장에는 사용자의 요청을 자연어에서 ES|QL 쿼리로 변환하는 esql 스킬도 포함되어 있습니다. 이 기술은 MCP 서버를 사용할 수 없는 경우 특히 유용합니다. 기본 통신이 터미널에서 실행되는 간단한 curl 명령에 의해 이루어지기 때문입니다. Elasticsearch는 어떤 프로젝트에도 쉽게 통합될 수 있는 풍부한 REST API 세트를 제공합니다. 이는 에이전틱 AI 애플리케이션을 개발할 때 특히 유용합니다.

Gemini CLI 확장 기능에 대한 자세한 내용은 여기 프로젝트 리포지토리에서 확인하세요.