博客

适用 Elasticsearch 的 Gemini CLI 扩展及工具和技能

Elastic 推出了适用于谷歌 Gemini CLI 的扩展，用于在开发人员和智能体工作流中搜索、检索和分析 Elasticsearch 数据。

Walter RafelsbergerEnrico Zimuel
集成智能体 AI

我们很高兴地宣布， Elastic 发布了适用于 Google 的 Gemini CLI 扩展，将 Elasticsearch 和 Elastic Agent Builder 的全部功能直接引入您的 AI 开发工作流。此扩展还提供几种最近开发的智能体技能，用于与 Elasticsearch 交互。

该扩展以开源项目的形式在此处提供。

Gemini CLI 是什么？如何安装？

Gemini CLI 是一个开源的 AI 智能体，它可将 Google 的 Gemini 模型直接引入命令行。它允许开发人员从终端与 AI 进行交互，以执行诸如生成代码、编辑文件、运行 shell 命令和从网上检索信息等任务。

与典型的聊天界面不同，Gemini CLI 可与您的本地开发环境集成，这意味着它可以直接在终端内理解项目上下文、修改文件、运行构建或测试，以及自动化工作流。这对于想要在不离开命令行工作流的情况下进行 AI 辅助编码和自动化的开发人员、网站可靠性工程师 (SREs) 和工程师来说非常有用。

Gemini CLI 可通过多个软件包管理器安装。最常用的方法是通过 npm 安装：

npm install -g @google/gemini-cli

如要了解其他安装选项，请参阅官方安装页面。

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

gemini

您会看到一个屏幕，如图 1 所示：

Gemini CLI 的屏幕截图。

图 1：Gemini CLI 屏幕截图。

配置 Elasticsearch

我们需要运行一个 Elasticsearch 实例。如要使用模型上下文协议 (MCP) 服务器，您还需要安装 Kibana 9.3+。如要使用下面描述的 Elasticsearch 查询语言 (ES|QL) 技能 (esql)，则不需要 Kibana。

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

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

这将在您的计算机上安装 Elasticsearch 和 Kibana，并生成一个用于配置 Gemini CLI 的 API 密钥。

API 密钥将显示为上一条命令的输出，并存储在 .env 文件中，该文件位于 elastic-start-local 文件夹。

如果您使用的是本地部署的 Elasticsearch（例如使用 start-local），并且您想将 Elastic Agent Builder 与 MCP 一起使用，那么您还需要连接一个大型语言模型 (LLM)。您可以阅读此文档页面以了解不同的选项。

如果您使用的是 Elastic Cloud（或无服务器架构），那么您已经预先建立了 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：

  • 从智能体处获取 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 密钥。如果您使用 start-local 运行 Elasticsearch，那么您已经在 start-local .env 文件中拥有了 ES_LOCAL_API_KEY。否则，您可以使用 Kibana 界面创建 API 密钥，详见此处：

  • 在 Kibana 中：Stack Management > Security > API 密钥 > 创建 API 密钥。

  • 我们建议仅设置 API 密钥的读取权限，并启用 feature_agentBuilder.read 权限，详见此处。

  • 复制已编码的 API 密钥值。

在您的 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 的单个索引，其中包含来自一家电子商务网站的 4675 个订单的信息。对于每笔订单，我们都有以下信息：

  • 客户信息（姓名、ID 号码、出生日期、电子邮件等）。

  • 订单日期。

  • 订单编号。

  • 产品（包含价格、数量、ID、类别、折扣和其他详情的所有产品列表）

  • SKU。

  • 总价（不含税，含税）。

  • 总数量。

  • 地理信息（城市、国家、洲、位置、地区）。

如要安装示例数据，请在 Kibana 中打开集成页面（在顶部搜索栏中搜索“集成”），然后安装示例数据。更多详情请参阅此处的文档。

本文旨在展示如何轻松配置 Gemini CLI 以连接到 Elasticsearch 并与 kibana_sample_data_ecommerce 索引交互。

如何使用 Elasticsearch MCP（模型上下文协议）

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

/mcp list

您应该会看到 elastic-agent-builder 已启用，如图 2 所示：

`elastic-agent-builder` MCP 服务器及其工具列表。

图 2：elastic-agent-builder MCP 服务器及其工具列表。

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` 命令。

图3：可用的 /elastic 命令。

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

/elastic:get-mapping kibana_sample_data_ecommerce

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

如何使用 Elasticsearch 的技能？

该扩展还附带了 ES|QL 的代理技能，ES|QL 是 Elasticsearch 中提供的 Elasticsearch 查询语言。Agent Skills 是一种开放格式，为 AI 编码智能体（如 Gemini CLI）提供特定任务的自定义指令。它们使用一种称为渐进式披露的概念，即在系统初始提示中只添加对技能的简要说明。当您要求智能体执行任务时，比如查询 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 服务器中可用，我们需要暂时禁用该服务器。您可以使用以下命令禁用它：

/mcp disable elastic-agent-builder

然后，您只需在 Gemini CLI 中输入类似这样的提示：

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

代理将：

  • 认识到 esql 技能的必要性。

  • 检查 kibana_sample_data_ecommerce 的模式。

  • 构建一个 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 模型如何通过显示其遵循的所有步骤来生成最终响应。在这里，您可以清楚地看到技能对模型推理过程的影响。当模型第一次意识到需要使用某项技能或执行 shell 命令时，它会采用人机协同的方式请求权限。

通过处理模式发现、查询生成和执行的繁重工作，esql 技能可以让您完全专注于答案，而不是获得答案的机制。您将获得所需的数据，格式正确且直接存储在终端中，无需写一行语法或切换到其他应用。

结论

在本文中，我们介绍了我们最近发布的适用于 Gemini CLI 的 Elasticsearch 扩展。此扩展让您可以使用 Gemini 和 Elastic Agent Builder 提供的 Elasticsearch MCP 服务器（从 9.3.0 版本开始提供）以及 /elastic 命令与您的 Elasticsearch 实例进行交互。

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

有关 Gemini CLI 扩展的更多信息，请访问此处的项目库。

相关内容

智能体 AI集成

使用 Elasticsearch 推理 API 以及 Hugging Face 模型

Jeffrey Rengifo
智能体 AI集成

使用 TypeScript 构建 Elasticsearch MCP 服务器

Jeffrey Rengifo
智能体 AI开发者体验集成

使用 Mastra 和 Elasticsearch 构建具有语义召回功能的知识代理

JD Armada
集成

为 Elasticsearch 注入活力：添加对原生 Prometheus API 的支持

Felix Barnsteiner

准备好打造最先进的搜索体验了吗？

足够先进的搜索不是一个人的努力就能实现的。Elasticsearch 由数据科学家、ML 操作员、工程师以及更多和您一样对搜索充满热情的人提供支持。让我们联系起来，共同打造神奇的搜索体验，让您获得想要的结果。

亲自试用