用于 Elasticsearch 的 Gemini CLI 扩展，包含工具和技能

作者：来自 Elastic Walter Rafelsberger 及 Enrico Zimuel

介绍 Elastic 为 Google 的 Gemini CLI 推出的扩展，使开发者和代理式工作流能够搜索、检索并分析 Elasticsearch 数据。

Elasticsearch 原生集成了业界领先的生成式 AI 工具和提供商。你可以查看我们的网络研讨会，了解如何超越 RAG 基础，或如何基于 Elastic 向量数据库构建生产就绪应用。

为了为你的使用场景构建最佳搜索解决方案，你可以立即开始免费云试用，或在本地机器上体验 Elastic。

---

我们很高兴地宣布推出 Elastic 为 Google Gemini CLI 打造的扩展，将 Elasticsearch 和 Elastic Agent Builder 的全部能力直接引入你的 AI 开发工作流。该扩展还提供了多个最近开发的 agent skills，用于与 Elasticsearch 交互。

该扩展已作为开源项目发布。

什么是 Gemini CLI，如何安装？

Gemini CLI 是一个开源 AI agent，将 Google 的 Gemini 模型直接带入命令行。它允许开发者通过终端与 AI 交互，以执行诸如生成代码、编辑文件、运行 shell 命令以及从 Web 检索信息等任务。

不同于典型的聊天界面，Gemini CLI 能够集成到你的本地开发环境中，这意味着它可以理解项目上下文、修改文件、运行构建或测试，并直接在终端内自动化工作流。这使它非常适合开发者、Site Reliability Engineers (SREs) 以及希望在命令行工作流中实现 AI 辅助编码和自动化的工程师。

Gemini CLI 可以通过多种包管理器进行安装，最常见的方法是通过 npm：

npm install -g @google/gemini-cli

如果你想了解其他安装方式，请参考官方安装页面。

安装完成后，运行以下命令启动 CLI：

gemini

你会看到一个界面，如图 1 所示：
图 1：Gemini CLI 的截图。

配置 Elasticsearch

我们需要有一个正在运行的 Elasticsearch 实例。如果你想使用 Model Context Protocol (MCP) 服务器，还需要安装 Kibana 9.3+。要使用下面描述的 Elasticsearch Query Language (ES|QL) 技能 (esql)，不需要 Kibana。

你可以在 Elastic Cloud 激活免费试用，或者使用 start-local 脚本在本地安装：

curl -fsSL https://elastic.co/start-local | sh

这将会在你的电脑上安装 Elasticsearch 和 Kibana，并生成一个用于配置 Gemini CLI 的 API key。

API key 会作为前一个命令的输出显示，并存储在 elastic-start-local 文件夹下的 .env 文件中。

如果你使用本地部署的 Elasticsearch（例如通过 start-local），并且想要使用 Elastic Agent Builder 配合 MCP，你还需要连接一个大型语言模型 (LLM)。你可以阅读这篇文档页面来了解不同的选项。

如果你使用 Elastic Cloud（或 serverless），你已经有一个预建的 LLM 连接。

安装 Elasticsearch 扩展

你可以使用以下命令为 Gemini CLI 安装 Elasticsearch 扩展：

gemini extensions install https://github.com/elastic/gemini-cli-elasticsearch

你可以通过打开 Gemini 并执行以下命令来检查扩展是否安装成功：

/extensions list

你应该能看到 Elasticsearch 扩展可用。

如果你想使用 MCP 集成，你需要安装 Elasticsearch 9.3+ 版本。你需要从 Kibana 获取 MCP 服务器 URL：

• 从 Agents > View all tools > Manage MCP > Copy MCP Server URL 获取 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 key。如果你使用 start-local 运行 Elasticsearch，你已经在 start-local 的 .env 文件中的 ES_LOCAL_API_KEY 中有该密钥。否则，你可以使用 Kibana 界面创建 API key，如下：

• 在 Kibana：Stack Management > Security > API Keys > Create API key。
• 建议只为 API key 设置只读权限，启用 feature_agentBuilder.read 权限，如此处所示。
• 复制编码后的 API key 值。

在你的 shell 中设置所需的环境变量：

export ELASTIC_URL="your-elasticsearch-url"
export ELASTIC_MCP_URL="your-elasticsearch-mcp-url"
export ELASTIC_API_KEY="your-encoded-api-key"

安装示例数据

你可以安装来自 Kibana 的电子商务订单数据集。它包含一个名为 kibana_sample_data_ecommerce 的索引，其中包含来自一个电子商务网站的 4,675 个订单信息。每个订单包含以下信息：

• 客户信息（姓名、ID、出生日期、邮箱等）
• 订单日期
• 订单 ID
• 产品（包含所有产品的价格、数量、ID、类别、折扣及其他详细信息的列表）
• SKU
• 总价（不含税、含税）
• 总数量
• 地理信息（城市、国家、大洲、位置、地区）

要安装示例数据，请在 Kibana 中打开 Integrations 页面（在顶部搜索栏搜索 "Integration"），并安装 Sample Data 。更多详情请参阅文档。

本文的目标是展示如何轻松配置 Gemini CLI 以连接 Elasticsearch 并与 kibana_sample_data_ecommerce 索引交互。

如何使用 Elasticsearch MCP

你可以在 Gemini 中使用以下命令检查连接：

/mcp list

你应该看到 elastic-agent-builder 已启用，如图 2 所示：
图 2：显示工具列表的 elastic-agent-builder MCP 服务器。

Elasticsearch 提供了一组默认工具。详见此处说明。

使用这些工具，你可以与 Elasticsearch 交互，提出诸如以下问题：

• 给我 Elasticsearch 中所有可用索引的列表/Give me the list of all the indexes available in Elasticsearch.。

• 在 Elasticsearch 的 kibana_sample_data_ecommerce 索引中，有多少客户位于美国？/How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

根据问题的不同，Gemini 会使用一个或多个可用工具尝试回答。

在 Gemini CLI 的 Elasticsearch 扩展中，我们还添加了 /elastic 命令。

如果你执行 /help 命令，你将看到所有可用的 /elastic 选项（图 3）：
图 3：可用的 /elastic 命令。

这些命令在你想直接执行 elastic-agent-builder MCP 服务器的特定工具时非常有用。例如，使用以下命令，你可以获取 kibana_sample_data_ecommerce 的映射：

/elastic:get-mapping kibana_sample_data_ecommerce

这些命令本质上是执行特定工具的快捷方式，而不是依赖 Gemini 模型来决定应该调用哪个工具。

如何使用 Elasticsearch 技能

此扩展还带有一个针对 ES|QL 的 agent 技能，即 Elasticsearch 中可用的 Elasticsearch Query Language。Agent Skills 是一个开放格式，为 AI 编码代理（如 Gemini CLI）提供特定任务的自定义指令。它们使用一种称为渐进披露（progressive disclosure）的概念，这意味着技能的简短描述仅被添加到初始系统提示中。当你要求代理执行某个任务（例如查询 Elasticsearch）时，它会将请求与相关技能匹配，并动态加载详细指令。这是一种在管理 token 预算的同时，为 AI 提供准确上下文的高效方法。

esql 技能设计用于让 Gemini CLI 直接对你的集群编写和执行 ES|QL 查询。ES|QL 是一种强大的管道查询语言，使数据探索、日志分析和聚合变得高度直观。启用此技能后，你无需查找 ES|QL 语法；只需向 Gemini CLI 提出关于数据的自然语言问题，代理将处理其余工作。

执行通过终端中的简单 curl 命令完成。这是可能的，因为 Elasticsearch 提供了丰富的 REST API 集，可轻松将系统集成到任何架构中。

esql 技能提供的功能：

• 索引和模式发现：代理可以使用技能的内置工具列出可用索引并获取字段映射。例如，在为 eCommerce 数据集编写查询之前，代理可以先对 kibana_sample_data_ecommerce 运行模式检查，以了解可用字段，如 taxful_total_price 或 category。

• 无缝自然语言翻译：该技能不仅提供普通参考手册，还提供解释用户意图的具体指南。当你输入自然语言请求，例如"Show average response time grouped by service"，代理会使用技能捆绑的模式匹配，将你的文字即时翻译为正确的 ES|QL 聚合、过滤和命令。

• 自我修正：如果查询失败（例如，由于类型不匹配或语法错误），技能会返回生成的查询及准确的 Elasticsearch 错误信息，使代理能够立即修正查询并重新尝试，无需你干预。

由于 esql 技能也可作为 elastic-agent-builder MCP 服务器中的工具使用，因此我们需要暂时禁用此服务器。你可以使用以下命令禁用它：

/mcp disable elastic-agent-builder

然后你可以直接在 Gemini CLI 中输入如下提示：

Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index

该 agent 将会：

• 识别需要使用 esql skill。
• 检查 kibana_sample_data_ecommerce 的 schema。
• 构建一个 ES|QL 查询，例如：FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5。
• 通过 Elasticsearch API 执行查询。
• 直接在终端向你展示最终结果。

这里，我们展示了 Gemini 对上一个提示的示例响应：

───────────────────────────────────────────────────────────
> Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index   ───────────────────────────────────────────────────────────
✓  Activate Skill "esql": Interact with Elasticsearch using ES|QL and curl. Use when querying, managing indices,  ...
Skill esql activated. Resources loaded from /home/user/.gemini/extensions/elasticsearch/skills/esql: 
Showing up to 200 items (files + folders).                                                                     /home/user/.gemini/extensions/elasticsearch/skills/esql/                                                            ├───SKILL.md 
└───references/
├───esql-reference.md 
├───generation-tips.md 
└───query-patterns.md

✦ I will start by exploring the mapping of the kibana_sample_data_ecommerce index to identify the fields for product category and sales revenue. Then, I will construct and execute an ES|QL query to determine the top 5 product categories by total sales revenue.

✓  Shell curl -s "${ELASTIC_URL%/}/kibana_sample_data_ecommerce/_mapping" -H "Authorization: ApiKey $(printenv ELAS...                                                                                                                       {  
   "kibana_sample_data_ecommerce": { 
     "mappings": { 
       "properties": {
         "category": { 
           "type": "text", 
           "fields": {
             "keyword": {
               "type": "keyword"
             }
           }
         }, 
         "currency": {
           "type": "keyword"
         }, 

✦ Okay, I have the mapping. The category is products.category.keyword and sales revenue is taxful_total_price. I'll now execute the ES|QL query to get the top 5 categories by revenue.

✓  Shell curl -s -X POST "${ELASTIC_URL%/}/_query" \  -H "Authorization: ApiKey $(printenv ELASTIC_API_KEY)" \  -H ...
{ 
   "took": 62,
   "is_partial": false, 
   "completion_time_in_millis": 1772805644164,
   "documents_found": 4675,
   "values_loaded": 12084, 
   "start_time_in_millis": 1772805644102, 
   "expiration_time_in_millis": 1773237644087,  
   "columns": [ 
     { 
       "name": "total_revenue",    
       "type": "double"  
     }, 
     {   
       "name": "products.category.keyword",

✦ The query for top 5 product categories by revenue was successful. I'll format the returned JSON values into a   user-friendly list.

 ✓  Shell 
                             
 Top 5 product categories by total sales revenue: 
 1. Men's Clothing: 149393.91
 2. Women's Clothing: 135099.91
 3. Women's Shoes: 105479.17
 4. Men's Shoes: 91797.92
 5. Women's Accessories: 60830.31 

✦ I've found the answer; now I'll format it for clarity.

 ✓  Shell 

 Here are the top 5 product categories by total sales revenue:                                                        
                                                                      
 | Rank | Category              | Total Revenue | 
 |------|-----------------------|---------------| 
 | 1    | Men's Clothing        | 149,393.91    |
 | 2    | Women's Clothing      | 135,099.91    |
 | 3    | Women's Shoes         | 105,479.17    |
 | 4    | Men's Shoes           | 91,797.92     | 
 | 5    | Women's Accessories   | 60,830.31     | 

✦ I've formatted and presented the answer. I'm finished.
 ───────────────────────────────────────────────────────────

有趣的是，Gemini 模型生成最终响应时，会展示它遵循的所有步骤。在这里，你可以清楚地看到 skill 对模型推理过程的影响。模型第一次识别出需要使用 skill 或执行 shell 命令时，它会通过 human-in-the-loop 方法请求权限。

通过处理 schema 发现、查询生成和执行等繁重工作，esql skill 让你可以完全专注于答案本身，而无需关心获取答案的具体机制。你将得到所需的数据，格式正确，直接显示在终端中，而无需写任何语法行或切换到其他应用程序。

结论

本文介绍了我们最近发布的 Gemini CLI 的 Elasticsearch 扩展。该扩展让你能够使用 Gemini 与 Elastic Agent Builder 提供的 Elasticsearch MCP server 交互（从版本 9.3.0 开始可用），并支持 /elastic 命令。

此外，该扩展还包含一个 esql skill，它可以将用户的自然语言请求转换为 ES|QL 查询。当 MCP server 无法使用时，这个 skill 特别有用，因为底层通信是通过在终端执行简单 curl 命令驱动的。Elasticsearch 提供了丰富的 REST API 集，可以轻松集成到任何项目中。这在开发 agentic AI 应用时尤为实用。

有关 Gemini CLI 扩展的更多信息，请访问项目仓库这里。

原文：https://www.elastic.co/search-labs/blog/gemini-cli-extension-elasticsearch