<![CDATA[Enrico Zimuel - Elasticsearch Labs]]> <![CDATA[Enrico Zimuel - Elasticsearch Labs]]> https://static-www.elastic.co/v3/assets/bltefdd0b53724fa2ce/blt1121c0bf0e8a6e65/6a88da6340a1841030ef456f/search-labs-thumbnail.png https://www.elastic.co/jp/search-labs/author/enrico-zimuel https://www.elastic.co/jp/search-labs/author/enrico-zimuel Fri, 18 Sep 2026 11:48:25 GMT <![CDATA[MastraとElasticsearchを使用してエージェント型AIアプリケーションを構築する方法]]> この記事では、Mastra TypeScriptフレームワークを使用して、Elasticsearchと連携するエージェント型アプリケーションを構築する方法をご紹介します。

最近、mastra-ai/mastraオープンソースプロジェクトに、ベクトルデータベースとしてのElasticsearchのサポートを追加しました。この新機能により、MastraでElasticsearchをネイティブに使用して埋め込みを保存できます。ベクターに加えて、Elasticsearchはコンテキストエンジニアリングの要件を満たすための高度な機能群を提供します（例：ハイブリッド検索と再ランク付け）。

この記事では、Elasticsearchを使用したRetrieval-Augmented Generation（RAG）アーキテクチャを実装するエージェントの作成について詳しく説明します。エージェント的なアプローチを使用して、Elasticsearchに保存されているSF映画データのコーパスを操作するデモプロジェクトを紹介します。このプロジェクトはelastic/mastra-elasticsearch-exampleで入手できます。

Mastra

Mastraは、エージェント型AIアプリケーションを作成するためのTypeScriptフレームワークです。

Mastraのプロジェクト構造は以下のようになります：

src/ ├── mastra/ │ ├── agents/ │ │ └── weather-agent.ts │ ├── tools/ │ │ └── weather-tool.ts │ ├── workflows/ │ │ └── weather-workflow.ts │ ├── scorers/ │ │ └── weather-scorer.ts │ └── index.ts ├── .env.example ├── package.json └── tsconfig.json

Mastraでは、エージェント、ツール、ワークフロー、スコアを作成できます。

エージェントは、インプットとしてメッセージを受け取り、アウトプットとして回答を生成するクラスです。エージェントは、ツール、大規模言語モデル（LLM）、およびメモリを使用できます（図1）。

Mastraでエージェントがどのように動作するかを示す図です。

エージェントのツールは、「外部の世界」と対話することを可能にします。たとえば、ウェブAPIと通信したり、Elasticsearchにクエリを実行するような内部操作を行ったりします。メモリコンポーネントは、過去の入力と出力を含む会話の履歴を格納するために非常に重要です。この格納されたコンテキストにより、エージェントは過去の対話を活用して、将来の質問に対してより情報に基づいた関連性の高い回答を提供できます。

ワークフローを使用すると、単一のエージェントの推論に頼るのではなく、明確で構造化されたステップを使用して複雑なタスクのシーケンスを定義できます（図2）。タスクをどのように分割し、データをどのように移動させ、何をいつ実行するかを網羅的に制御できます。ワークフローは、デフォルトで組み込みの実行エンジンを使用して実行されますが、ワークフローランナーにデプロイすることもできます。

Mastraのワークフローの例。

Mastraでは、スコアを定義することもできます。スコアは、モデル評価、ルールベース、統計的な方法を用いてエージェントの出力を評価する自動テストです。スコアラーはスコアを返します。これは、出力が評価基準をどれだけ満たしているかを定量化する数値（通常0から1の間）です。これらのスコアにより、パフォーマンスを客観的に追跡し、さまざまなアプローチを比較し、AIシステムの改善すべき分野を特定することができます。スコアラーは、独自のプロンプトやスコアリング関数でカスタマイズできます。

Elasticsearch

デモプロジェクトを実行するには、Elasticsearchインスタンスを実行する必要があります。Elastic Cloudで無料トライアルを有効化するか、start-localスクリプトを使ってローカルにインストールできます。

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

これにより、ElasticsearchとKibanaがコンピュータにインストールされ、Mastraインテグレーションの設定に使用するAPIキーが生成されます。

APIキーは前のコマンドの出力として表示され、elastic-start-localフォルダー内の.envファイルに保存されます。

デモをインストールして設定

デモプロジェクトのソースコードを含む elastic/mastra-elasticsearch-example リポジトリを作成しました。リポジトリに記載されている例は、Elasticsearchからドキュメントを取得するためのRAGアーキテクチャを実装したエージェントをMastraで作成する方法を示しています。

SF映画のデモ用データセットを提供しました。Kaggle上のIMDbデータセットから500本の映画を抽出しました。

最初のステップは、次のコマンドを使用してnpmでプロジェクトの依存関係をインストールします：

npm install

次に、設定内容を格納する.envファイルを構成する必要があります。以下のコマンドを使用して、 .env.exampleファイルの構造をコピーすることで、このファイルを生成できます。

cp .env.example .env

これで、.envを編集できるようになりました。不足している情報を追加します：

OPENAI_API_KEY= ELASTICSEARCH_URL= ELASTICSEARCH_API_KEY= ELASTICSEARCH_INDEX_NAME=scifi-movies

Elasticsearchインデックスの名称は scifi-moviesです。必要であれば、環境変数 ELASTICSEARCH_INDEX_NAMEを使って変更できます。

OpenAIを埋め込みサービスとして使用しました。これは、OPENAI_API_KEY環境変数にOpenAIのAPIキーを提供する必要があることを意味します。

例で使用されている埋め込みモデルは openai/text-embedding-3-small であり、埋め込み次元は1,536です。

最終的な答えを導き出すために、openai/gpt-5-nano モデルを使用してコストを削減しました。

RAGアーキテクチャでは、回答の妥当性を検証するという重労働は検索コンポーネント（この場合は Elasticsearch）が行うため、それほど強力ではない（そして一般的に安価な）最終的なLLMモデルを使用することができます。

小規模なLLMは主に2つのタスクを担当します：

  • クエリの言い換え/埋め込み：ユーザーの自然言語の質問をセマンティック検索用のベクトル埋め込みに変換します。

  • 回答の合成：取得された関連性の高いコンテキストの断片（文書/動画）を取り出し、提示された指示に従って、首尾一貫した最終的な人間が読める回答に合成します。

RAGプロセスは回答に必要とされる正確な事実的文脈を提供するため、最終的なLLMは大規模または高度に複雑である必要はなく、必要な知識をすべて自らのパラメータ内に持つ必要もありません（それは大規模で高価なモデルが優れている領域です）。本質的には、本格的なナレッジベースとしてではなく、Elasticsearchが提供するコンテキストの洗練されたテキストサマライザーおよびフォーマッターとして機能します。これにより、コストやレイテンシーの最適化にgpt-5-nanoのようなモデルを活用できます。

.envファイルの設定後、次のコマンドで映画をElasticsearchに取り込むことができます。

npx tsx src/utility/store.ts

次のような出力が表示されるはずです。

🚀 Starting ingestion of 500 movies from 500_scifi_movies.jsonl... Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 1/500 (0%) | ok:1 | fail:0 | chunks:1 | eta:19m 33s | current:Capricorn One Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 2/500 (0%) | ok:2 | fail:0 | chunks:2 | eta:10m 32s | current:Doghouse Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 3/500 (1%) | ok:3 | fail:0 | chunks:3 | eta:7m 33s | current:Dinocroc Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 4/500 (1%) | ok:4 | fail:0 | chunks:7 | eta:6m 10s | current:Back to the Future Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 5/500 (1%) | ok:5 | fail:0 | chunks:9 | eta:5m 14s | current:The Projected Man Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 6/500 (1%) | ok:6 | fail:0 | chunks:11 | eta:4m 41s | current:I, Robot ... ✅ Ingestion complete in 1m 46s. Success: 500, Failed: 0, Chunks: 693.

scifi-moviesインデックスのマッピングには、次のフィールドが含まれています。

  • 埋め込み、1536次元のdense_vector、コサイン類似度。

  • 説明、映画の説明を含むテキスト。

  • 監督、監督の名前を含むテキスト。

  • タイトル、映画のタイトルを含むテキスト。

タイトルとディスクリプションを使用して埋め込みを生成しました。タイトルとディスクリプションは2つの別個のフィールドであるため、両者を連結することで、結果として得られる埋め込みベクトルが、映画の具体的で独自の特徴（タイトル）と豊かな説明的コンテキスト（内容説明）の両方を捉えることができます。これにより、より正確で包括的なセマンティック検索結果が得られます。この結合されたインプットにより、埋め込みモデルは類似度マッチングに向けて、ドキュメントのコンテンツをより適切に単一のベクトル表現として捉えることができます。

デモを実行

次のコマンドでデモを実行できます：

npm run dev

このコマンドを実行するとlocalhost:4111でWebアプリケーションが起動し、Mastra Studioにアクセスできるようになります（図3）。

Elasticsearch Agentの例を使用したMastra Studioのスクリーンショット。

Mastra Studio はエージェントの構築とテストのためのインタラクティブなUIを提供し、さらにMastraアプリケーションをローカルサービスとして公開するREST APIも備えています。これにより、統合を気にせずにすぐに構築を始められます。

Elasticsearchを使ったセマンティック検索を実行するツールとして、MastraのcreateVectorQueryToolを使ったElasticsearch Agentを提供しました。このエージェントは、RAGアプローチを使用して関連文書（つまり映画）を検索し、ユーザーの質問に答えます。

このエージェントは以下のプロンプトを使用します：

You are a helpful assistant that answers questions based on the provided context. Follow these steps for each response: 1. First, carefully analyze the retrieved context chunks and identify key information. 2. Break down your thinking process about how the retrieved information relates to the query. 3. Draw conclusions based only on the evidence in the retrieved context. 4. If the retrieved chunks don't contain enough information, explicitly state what's missing. Format your response as: THOUGHT PROCESS: - Step 1: [Initial analysis of retrieved chunks] - Step 2: [Reasoning based on chunks] FINAL ANSWER: [Your concise answer based on the retrieved context] Important: When asked to answer a question, please base your answer only on the context provided in the tool. If the context doesn't contain enough information to fully answer the question, please state that explicitly and stop it. Do not add more information than what is present in the retrieved chunks. Remember: Explain how you're using the retrieved information to reach your conclusions.

Mastra Studio > AgentsメニューをクリックしてElasticsearch Agentを選択すると、チャットシステムを使用してエージェントをテストできます。たとえば、SF映画に関する情報を次のような質問で尋ねることができます。

UFOを題材にした映画またはテレビシリーズを5つ見つけてください。

エージェントがvectorQueryToolを実行することがわかります。起動したツールをクリックすると、入力と出力を確認できます。実行の最後に、LLMはElasticsearchのscifi-moviesインデックスから得られたコンテキストに基づいて、あなたの質問に回答します（図4）。

Elasticsearch Agentを使用したLLMからの対応。

Mastraは内部で以下の手順を実行します：

  1. ベクトル変換：ユーザーの質問「UFOに関する映画やテレビシリーズを5つ探して」は、OpenAIのopenai/text-embedding-3-smallモデルを使ってベクトル埋め込みに変換されます。

  2. ベクトル検索：この埋め込みはその後、Elasticsearchに対してベクトル検索を用いてクエリを実行するために使用されます。

  3. 結果の取得：Elasticsearchは、クエリに非常に関連性の高い10本の映画（つまり、ユーザーのクエリベクトルに最も近いベクトルを持つ映画）を返します。

  4. 回答生成：取得された映画と元のユーザーの質問は、具体的にはopenai/gpt-5-nano LLM に送信されます。LLMはこの情報を処理し、最終的な回答を生成することで、ユーザーの5つの結果への要望を確実に満たします。

Elasticsearch エージェント

ここではElasticsearch Agentのソースコードを報告しました。

import { Agent } from "@mastra/core/agent"; import { ElasticSearchVector } from '@mastra/elasticsearch'; import { createVectorQueryTool } from '@mastra/rag'; import { ModelRouterEmbeddingModel } from "@mastra/core/llm"; import { Memory } from "@mastra/memory"; const es_url = process.env.ELASTICSEARCH_URL; const es_apikey = process.env.ELASTICSEARCH_API_KEY; const es_index_name = process.env.ELASTICSEARCH_INDEX_NAME; const prompt = 'insert here the previous prompt'; const esVector = new ElasticSearchVector({ id: 'elasticsearch-vector', url: es_url, auth: { apiKey : es_apikey } }); const vectorQueryTool = createVectorQueryTool({ vectorStore: esVector, indexName: es_index_name, model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small") }); export const elasticsearchAgent = new Agent({ id: "elasticsearch-agent", name: "Elasticsearch Agent", instructions: prompt, model: 'openai/gpt-5-nano', tools: { vectorQueryTool }, memory: new Memory(), });

vectorQueryToolは、RAGの例における取得部分を実装するために呼び出されるツールです。MastraにElasticが提供したElasticSearchVector実装を使用しています。

エージェントは、vectorQueryTool、プロンプト、およびメモリを消費するエージェントクラスのオブジェクトです。ご覧のように、Elasticsearchをエージェントに接続するために必要なコードはごくわずかです。

まとめ

この記事では、ElasticsearchとMastraフレームワークを統合し、洗練されたエージェント型AIアプリケーションを構築することのシンプルさとパワーについて実証しました。具体的には、Elasticsearchでインデックス化されたSF映画データのコーパスに対してセマンティック検索を実行できるRAGエージェントの作成について説明しました。

重要なポイントは、ElasticがMastraのオープンソースプロジェクトに直接貢献し、ベクターストアとしてのElasticsearchをネイティブサポートしていることです。この統合により、導入時の障壁が大幅に低下します。これは、 Elasticsearch Agentのソースコードを見れば明らかです。ElasticSearchVectorとcreateVectorQueryToolを使用することで、Elasticsearchをエージェントに接続するための総合的なセットアップが、最小限の設定コード行数で済みます。

Elasticsearchは、結果の関連性を高めるためのいくつかの高度な機能を提供しています。例として、ハイブリッド検索は、語彙検索とベクトル検索を組み合わせることで、精度を大幅に向上させます。もう一つの興味深い機能は、ハイブリッド検索の最後に適用できる最新のJinaモデルを使用した再ランク付けです。これらの技術についてさらに詳しく知るには、Elasticsearch Labsの以下の記事を参照してください。

また、提供されている例を参考に、MastraとElasticsearchを使って独自のデータ駆動型エージェントを構築し始めることをお勧めします。Mastraについての詳細は、 こちらのオフィシャルドキュメントをご覧ください。

]]> https://www.elastic.co/search-labs/blog/build-agentic-ai-applications-mastra-elasticsearch https://www.elastic.co/search-labs/blog/build-agentic-ai-applications-mastra-elasticsearch Wed, 08 Apr 2026 00:00:00 GMT <![CDATA[ElasticsearchのGemini CLI拡張機能（ツールとスキル付き）]]> GoogleのGemini CLI用のElastic拡張機能のリリースを発表できることを嬉しく思います。これにより、ElasticsearchとElastic Agent Builderのパワーを、AI開発ワークフローに直接組み込むことができます。この拡張機能には、Elasticsearchを操作するための最近開発されたエージェントスキルもいくつか用意されています。

この拡張機能はオープンソースプロジェクトとしてこちらから利用できます。

Gemini CLIの概要とインストール方法

Gemini CLI は、GoogleのGeminiモデルを直接コマンドラインに取り込むオープンソースのAIエージェントです。ターミナルからAIと対話することで、コードの生成、ファイルの編集、シェルコマンドの実行、ウェブからの情報の取得などのタスクを実行できます。

一般的なチャットインターフェースとは異なり、Gemini CLIはローカル開発環境と統合されます。つまり、プロジェクトのコンテキストを理解し、ファイルを変更し、ビルドやテストを実行し、ワークフローをターミナル内で直接自動化することができます。開発者、サイト信頼性エンジニア（SRE）、コマンドラインのワークフローを離れることなくAI支援のコーディングと自動化を求めるエンジニアにとって役立ちます。

Gemini CLIは複数のパッケージマネージャーを使ってインストール可能です。最も一般的な方法はnpm経由です。

npm install -g @google/gemini-cli

その他のインストール方法については、公式のインストールページを参照してください。

インストール後、以下のコマンドを実行してCLIを起動します。

gemini

図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キーは前のコマンドの出力として表示され、 elastic-start-localフォルダ内の.envファイルに保存されます。

オンプレミスのElasticsearchを使用している場合（例えば、start-local）、MCPでElastic Agent Builderを使用するには、大規模言語モデル（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ページの最上部に表示されます。Elasticsearchをstart-localで実行している場合、 start-local .envファイルのES_LOCAL_URLキーにエンドポイントが既に存在します。

APIキーも必要です。Elasticsearchをstart-localで実行している場合、 start-local .envファイルには既にES_LOCAL_API_KEYが含まれています。それ以外の場合は、こちらに記載されているように、Kibanaインターフェースを使用してAPIキーを作成できます。

  • Kibanaでは、[スタック管理] > [セキュリティ] > [APIキー] > [APIキーの作成] の順に操作します。

  • API キーには読み取り権限のみを設定し、ここに記載されているようにfeature_agentBuilder.read権限を有効にすることをお勧めします。

  • エンコードされたAPIキーの値をコピーしてください。

シェルで必要な環境変数を設定してください。

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

サンプルデータセットをインストールする

Kibanaから入手可能なeCommerce ordersデータをインストールできます。このデータベースには、eコマースWebサイトからの4,675件の注文に関する情報を含むkibana_sample_data_ecommerceという単一のインデックスが含まれています。各注文について、次の情報があります。

  • 顧客情報（名前、ID、生年月日、メールなど）。

  • 注文日。

  • 注文ID。

  • 商品（価格、数量、ID、カテゴリー、割引、その他の詳細を含む全商品のリスト）

  • SKU。

  • 合計金額（税抜、税込）。

  • 合計数量。

  • 地理情報（都市、国、大陸、場所、地域）。

サンプルデータをインストールするには、Kibanaの統合ページを開き（検索トップバーで「Integration」を検索）、Sample Dataをインストールしてください。詳細については、こちらのドキュメントを参照してください。

この記事の目的は、Gemini CLIをElasticsearchに接続し、kibana_sample_data_ecommerceインデックスとやり取りするのがいかに簡単かを示すことです。

Elasticsearch MCPの使用方法

Geminiで以下のコマンドを使用して接続状況を確認できます。

/mcp list

図2に示すように、 elastic-agent-builderが有効になっているはずです。

ツールのリストを備えた「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` コマンド。

これらのコマンドは、elastic-agent-builder MCPサーバーの特定のツールを直接実行したい場合に便利です。例えば、以下のコマンドを使用すると、 kibana_sample_data_ecommerceのマッピングを取得できます。

/elastic:get-mapping kibana_sample_data_ecommerce

これらのコマンドは、どのツールを呼び出すかをGeminiモデルに頼るのではなく、基本的に特定のツールを実行するためのショートカットです。

Elasticsearchスキルの使用方法

この拡張機能には、Elasticsearchで利用可能なElasticsearchクエリ言語であるES|QL用のエージェントスキルも付属しています。エージェントスキル は、Gemini CLIのようなAIコーディングエージェントに特定のタスクに合わせたカスタム指示を提供するオープンフォーマットです。段階的開示と呼ばれる概念を採用しており、最初のシステムプロンプトにスキルの簡単な説明のみを追加します。エージェントにElasticsearchへのクエリなどのタスクを実行するように依頼すると、リクエストが関連するスキルと照合され、詳細な指示が動的に読み込まれます。これは、トークン予算を効率的に管理すると同時に、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 のような利用可能なフィールドを理解することができます。

  • シームレスな自然言語翻訳：スキルはエージェントに単なるリファレンスマニュアルにとどまらず、ユーザーの意図を解釈するための具体的なガイドを提供します。「サービス別にグループ化された平均応答時間を表示して」といった自然言語によるリクエストを入力すると、エージェントはスキルのバンドルされたパターンマッチングを使用して、入力された言葉を即座に正しい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のスキーマを確認してください。

  • 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からの回答例を報告します。

─────────────────────────────────────────────────────────── > 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モデルが最終的な応答を生成する際にどのような手順を踏むかは非常に興味深い点です。ここでは、モデルの推論プロセスにおけるスキルの影響が明確に見て取れます。モデルがスキルを使用する必要がある、またはシェルコマンドを実行する必要があると初めて認識したとき、ヒューマン・イン・ザ・ループ方式を使用して許可を要求します。

スキーマの発見、クエリの生成、実行といった面倒な作業をesqlスキルが処理することで、回答を得るための仕組みではなく、回答そのものに集中できるようになります。必要なデータが、適切な形式でターミナルに直接表示されます。構文を記述したり、別のアプリケーションに切り替えたりする必要は一切ありません。

まとめ

この記事では、最近リリースしたGemini CLI用のElasticsearch拡張機能を紹介しました。この拡張機能を使用すると、GeminiおよびElastic Agent Builderが提供するElasticsearch MCPサーバー（バージョン 9.3.0 以降で利用可能）と/elasticコマンドを使用してElasticsearchインスタンスとやり取りできます。

さらに、この拡張機能には、ユーザーの自然言語からのリクエストをES|QLに変換する esqlスキルも含まれています。このスキルは、MCPサーバーが使用できない場合に特に役立ちます。なぜなら、基本的な通信はターミナルで実行されるシンプルなcurlコマンドによって行われるためです。Elasticsearchは、あらゆるプロジェクトに簡単に統合できる豊富なREST APIセットを提供します。これは特にエージェント型AIアプリケーションの開発時に有用です。

Gemini CLI拡張機能の詳細についてはこちらのプロジェクトリポジトリをご覧ください。

]]> https://www.elastic.co/search-labs/blog/gemini-cli-extension-elasticsearch https://www.elastic.co/search-labs/blog/gemini-cli-extension-elasticsearch Tue, 17 Mar 2026 00:00:00 GMT <![CDATA[Google MCP Toolbox for DatabasesにElasticsearchサポートを導入]]> この記事では、Google MCP ToolboxとElasticsearchを併用し、Elasticsearchインデックスから情報を抽出する簡単なツールを構築する方法を解説します。

当社は最近、Google MCP Toolbox for Databasesのオープンソースプロジェクトに貢献し、Elasticsearchをデータベースとしてサポートしました。

この新しい機能により、Google MCP Toolboxを使用してElasticsearchに接続し、データと直接「会話」できるようになりました。

Elasticsearch

Elasticsearchインスタンスを実行する必要があります。Elastic Cloudで無料トライアルを有効化するか、start-localスクリプトを使ってローカルにインストールできます。

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

これにより、ElasticsearchとKibanaがコンピュータにインストールされ、Google MCP Toolboxの設定に使用するAPIキーが生成されます。

APIキーは前のコマンドの出力として表示され、elastic-start-localフォルダー内の.envファイルに保存されます。

サンプルデータセットをインストールする

インストール後、ユーザー名elasticとstart-localスクリプトによって生成されたパスワード（.envファイルに保存）を使用してKibanaにログインできます。

Kibanaから入手可能なeCommerce ordersデータをインストールできます。このデータベースには、eコマースWebサイトからの4,675件の注文に関する情報を含むkibana_sample_data_ecommerceという単一のインデックスが含まれています。各注文について、次の情報があります。

  • 顧客情報（氏名、ID、生年月日、メールアドレスなど）

  • 注文日

  • 注文ID

  • 商品（価格、数量、ID、カテゴリー、割引などを含む全商品のリスト）

  • SKU

  • 合計金額（税抜、税込）

  • 合計数量

  • 地理情報（都市、国、大陸、場所、地域）

サンプルデータをインストールするには、Kibanaの統合ページを開き（検索トップバーで「Integration」を検索）、「Sample Data」をインストールしてください。詳細については、ドキュメントhttps://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibanaを参照してください。

この記事の目的は、Google MCP ToolboxがElasticsearchに接続し、自然言語でkibana_sample_data_ecommerceインデックスとやり取りするのがいかに簡単かを示すことです。

Google MCP Toolbox

Google MCP ToolboxはオープンソースのMCPサーバーで、アプリケーションやAIエージェントが安全かつ効率的にデータベースとやり取りできるように設計されています。以前は「GenAI Toolbox for Databases」と呼ばれていたこのプロジェクトは、モデルコンテキストプロトコル（MCP）との完全な互換性を採用した後に改名されました。その目的は、エージェントをデータベースに接続する際に従来必要とされていた接続プーリング、認証、オブザーバビリティ、その他の運用上の懸念をバックエンドで処理することで、重労働を排除することです。

Toolboxの本質は、開発者がデータベースのやり取りをカプセル化する再利用可能な高レベルのツールを定義できるようにすることです。これらのツールは、AIエージェントなどのMCP互換クライアントならどれでも起動できます。クライアントが低レベルのSQLクエリを実装したり、データベース接続を管理したりする必要はありません。このアプローチにより、データベース対応エージェントの構築に必要な定型コードの量が大幅に削減され、わずか数行のアプリケーションロジックに高度なデータ操作を統合できるようになります。ツールが定義されると、複数のエージェント、フレームワーク、言語間で共有できます（図1）。

Toolboxを使用する大きな利点は、組み込まれたセキュリティモデルです。OAuth2やOIDCなどの認証フローはネイティブにサポートされているため、開発者はデータベースの機密認証情報をエージェントで処理したり格納したりする必要がありません。このプラットフォームは、デバッグ、監視、本番環境への導入に不可欠な、OpenTelemetryによる指標やトレースなどの観測機能も提供します。全体として、MCP Toolboxは、あらゆるMCP対応システムのデータを操作するための、統一された安全で拡張可能なインターフェースとして機能します。

MCP Toolboxのインストール方法

MCP ToolboxサーバーをLinuxにインストールするには、次のコマンドを使用します。

export VERSION=0.21.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox chmod +x toolbox

macOSまたはWindowsにインストールする場合は、ここに記載されている手順に従ってください。

Elasticsearch向けにToolboxを構成する

Elasticsearch向けにMCP Toolboxを構成するには、次のようにtools.yamlファイルを作成する必要があります。

sources: my-cluster: kind: elasticsearch addresses: - http://localhost:9200 apikey: <insert-here-api-key> tools: customer-orders: kind: elasticsearch-esql source: my-cluster description: Get the orders made by a customer identified by name. query: | FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name, {"operator": "AND"}) parameters: - name: name type: string description: The customer name. toolsets: elasticsearch-tools: - customer-orders

<insert-here-api-key>値を有効なElasticsearch APIキーに置き換える必要があります。start-localを使用してElasticsearchをローカルで実行している場合は、start-localによって生成された.envファイルのES_LOCAL_API_KEY変数の下にAPIキーがあります。Elastic Cloudを使用している場合はここで説明した手順に従うことでAPIキーを生成できます。

前のツールには、Elasticsearch用の次のES|QLクエリが含まれています。

ES|QLに慣れていない方のために説明すると、ES|QLはSQLと同様にElasticが開発したクエリ言語で、1つ以上のインデックスを検索するために使用できます。ES|QLの詳細についてはこちらの公式ドキュメントをご覧ください。

上記のクエリは、kibana_sample_data_ecommerceインデックスに格納されている指定顧客名を含むすべての注文を?nameパラメーター（疑問符はパラメーターを示します）を用いて検索します。

顧客名は、以前のYAML設定で文字列型と「顧客名」という記述で定義されています。

このツールを使用すると、顧客の注文に関する質問に答えることができます。たとえば、「顧客Fooは2025年10月に何件の注文をしましたか？」

ツールとそのパラメーターの説明は、ユーザーの自然言語リクエストから関連情報を抽出するために不可欠です。この抽出は、大規模言語モデル（LLM）の関数呼び出し機能を使用して実行されます。実際には、LLMは、必要な情報を取得するためにどの機能（ツール）を実行する必要があるかを判断し、その機能に適したパラメーターも取得できます。

詳細については、Elasticsearchを使用したOpenAIの関数呼び出しに関するAshish Tiwariの記事を読むことをお勧めします。

Toolboxサーバーを実行する

次のコマンドで、以前のtools.yamlファイルを使用してMCPツールボックスを実行できます。

./toolbox --tools-file tools.yaml --ui

–uiパラメーターはhttp://127.0.0.1:5000/uiのウェブアプリケーションを実行します（図2）。

[ツール] > [customer-orders] を選択し、パラメータ名に顧客名（例：Gwen Sanders）を挿入して [ツールを実行] ボタンをクリックします。図3に示すように、JSON応答が表示されます。

セットアップが完了すると、MCP Toolboxはcustomer-ordersツールを実行してElasticsearchと通信し、ES|QLクエリを実行できるようになります。

Gemini CLIでのMCP Toolboxの使用

任意のMCPクライアントを使用して、MCP Toolbox for Databasesと通信できます。例えば、Gemini CLIというコマンドラインツールを使ってGeminiを使うことができます。Gemini CLIのインストールは、こちらの手順に従って行うことができます。

Gemini CLIは、MCP Toolbox用の事前設定された拡張機能を提供しており、gemini-cli-extensions/mcp-toolboxで入手できます。この拡張機能は次のコマンドを実行してインストールできます。

gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

インストール後、MCP Toolbox用のtools.yaml設定ファイルを格納したディレクトリに移動し、以下のようにGemini CLIを実行する必要があります（この手順は、Gemini CLIをMCP Toolboxで自動的に設定するために必要です）。

gemini

図4に示すように出力広告が表示されます。

次のコマンドを使用して、MCP Toolboxが接続されているかどうかを確認できます。

/mcp list

mcp_toolboxとcustomer-orders ツールが一覧に表示されているはずです（図5）。

MCP ToolboxがGemini CLI に接続されている場合は、「顧客Gwen Sandersの注文を教えてください」などの質問をいくつか試すことができます。Gemini CLIは、mcp_toolboxサーバーからcustomer-ordersツールを実行する許可を要求します（図6を参照）。

確認後、Gemini CLIはMCP Toolboxへのリクエストを実行し、結果としてJSON応答を取得し、それを使用して応答をフォーマットします（図7）。

Gemini CLIからの応答で、Gwen Sandersが2つの製品を1回の注文で、合計132ユーロの価格で購入したことがレポートされます。

MCP Toolbox SDKs

Google MCP Toolboxは、Go、Python、Javascriptで書かれたプログラムからすべての機能にアクセスするためのSDKも提供しています。

例えば、Python SDKはGithubの次のページhttps://github.com/googleapis/mcp-toolbox-sdk-pythonで入手可能です。

MCP Toolboxに接続するための簡単なエージェントを作成する必要があります。次のパッケージをインストールする必要があります。

pip install toolbox-core pip install google-adk

次のコマンドを使用して、新しいエージェントプロジェクトを作成します。

adk create my_agent

これにより、ファイルagent.pyを持つ新しいディレクトリがmy_agentとして作成されます。

Toolboxに接続するには、次の内容でmy_agent/agent.pyを更新します。

from google.adk import Agent from google.adk.apps import App from toolbox_core import ToolboxSyncClient client = ToolboxSyncClient("http://127.0.0.1:5000") root_agent = Agent( name='root_agent', model='gemini-2.5-flash', instruction="You are a helpful AI assistant designed to search information about a dataset of ecommerce orders.", tools=client.load_toolset(), ) app = App(root_agent=root_agent, name="my_agent")

Google APIキーを使用して.envファイルを作成します。

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env

最後に、エージェントを実行して結果を確認します。エージェントを実行するには、次のコマンドを実行します。

adk run my_agent

または、Webインターフェース経由で提供することもできます。

adk web --port 8000

両方の場合において、Q&Aインターフェースを使用してMCP Toolboxと対話することができます。たとえば、先程の質問「顧客Gwen Sandersの注文を教えてください」をすることができます。

さまざまなSDKの詳細については、このドキュメントページをご参照ください。

まとめ

この記事では、Google MCP Toolbox for DatabasesのElasticsearch統合について説明しました。シンプルなYAML設定ファイルを使用して、自然言語の質問をES|QL言語を使用してElasticsearchクエリに変換する一連のツールを定義できます。

eコマースWebサイトからの注文を含むkibana_sample_data_ecommerceデータセットとの対話方法を示しました。この設定ファイルを使用すると、MCP Toolboxサーバーを簡単に実行し、任意のMCPクライアントから接続できます。

最後に、Gemini CLIをクライアントとして使用してMCP Toolbox for Databasesに接続し、Elasticsearchに保存されているeコマースデータをクエリする方法を示しました。特定の顧客の名前で識別された注文情報を取得するために自然言語クエリを実行しました。

MCPエコシステムが成長し続けるにつれて、このパターン（安全で本番環境ですぐに使えるインフラストラクチャーに裏打ちされた軽量なツール定義）は、最小限の労力で、ますます有能でデータを認識するエージェントを構築する新しい機会を生み出します。MCP Toolboxは、Elasticのサンプルデータセットを使ってローカルで実験する場合でも、大規模なアプリケーションに検索機能を統合する場合でも、自然言語を使ってElasticsearchのデータを操作するための、信頼性と拡張性に優れた基盤を提供します。

エージェントAIアプリケーションの開発の詳細については、Anish MathurとDana Juratoniによる記事「Elasticsearchを使用したAI エージェントワークフローの構築」をお読みください。

Google MCP Toolboxの詳細については、https://googleapis.github.io/genai-toolbox/getting-started/introduction/をご覧ください。

]]> https://www.elastic.co/search-labs/blog/google-mcp-toolbox-elasticsearch-support https://www.elastic.co/search-labs/blog/google-mcp-toolbox-elasticsearch-support Fri, 12 Dec 2025 00:00:00 GMT <![CDATA[ES|QLからPHPオブジェクトへ]]> elasticsearch-php v8.13.0以降では、 ES|QLクエリを実行し、結果をstdClassの PHP オブジェクトまたはカスタム クラスにマップできます。

ES|QL

ES|QLは、Elasticsearch 8.11.0 で導入された新しい Elasticsearch クエリ言語です。現在、テクニカル プレビューで利用可能です。Elasticsearch に保存されているデータをフィルタリング、変換、分析するための強力な方法を提供します。

「パイプ」（ | ）を使用して、データを段階的に操作および変換します。このアプローチにより、ユーザーは一連の操作を構成でき、1 つの操作の出力が次の操作の入力となり、複雑なデータ変換と分析が可能になります。

たとえば、次のクエリは、 sample_dataインデックスの最初の 3 つのドキュメント (行) を返します。

FROM sample_data | LIMIT 3 ES|QLはテーブルを生成する

ユースケース: 公式 PHP クライアントの ES|QL 機能

公式 PHP クライアントで開発された ES|QL 機能を説明するために、次の情報を含む 81,828 冊の書籍 (54.4 MB) のCSV ファイルをElasticsearch に保存しました。

Title;Descrition;Author;Year;Publisher;Ratings

このリストは、公開されているAmazon Books Reviews データセットから抽出しました。

次の Elasticsearch マッピングを使用してbooksインデックスを作成しました:

'mappings' : { 'properties': { 'title': { 'type': 'text' }, 'description': { 'type': 'text' }, 'author': { 'type': 'text' }, 'year': { 'type': 'short' }, 'publisher': { 'type': 'keyword' }, 'rating': { 'type': 'half_float' } } }

rating値は、2.9 GB のBooks_rating.csvファイルから取得されたランキングレビューの平均です。

ここでは、 Elasticsearch にすべての書籍を一括インポートするために使用した PHP スクリプトを見つけることができます。一括操作には PHP 8.2.17 を使用して 7 秒と 28 MB の RAM が必要でした。提案されたマッピングでは、Elasticsearch のインデックス サイズは約 62 MB になります。

ES|QL の結果を PHP オブジェクトまたはカスタム クラスにマッピングする

esql()->query()エンドポイントを使用して、PHP で ES|QL クエリを実行できます。このクエリの結果はテーブル データ構造になります。これは、 columnsフィールドとvaluesフィールドを使用して JSON で表現されます。columnsフィールドにはnameとtype定義があります。

以下は、ユーザーのランキングレビュー順に並べられた、Stephen King が書いたトップ 10 の本を取得する ES|QL クエリの例です。

$query = <<<EOD FROM books | WHERE author == "Stephen King" | SORT rating DESC | LIMIT 10 EOD; $result = $client->esql()->query([ 'body' => ['query' => $query] ]);

Elasticsearch からの JSON 結果は次のようになります。

{ "columns": [ { "name": "author", "type": "text" }, { "name": "description", "type": "text" }, { "name": "publisher", "type": "keyword" }, { "name": "rating", "type": "double" }, { "name": "title", "type": "text" }, { "name": "year", "type": "integer" } ], "values": [ [ "Stephen King", "The author ...", "Turtleback", 5.0, "How writers write", 2002 ], [ "Stephen King", "In Blockade Billy, a retired coach...", "Simon and Schuster", 5.0, "Blockade", 2010 ], [ "Stephen King", "A chilling collection of twenty horror stories.", "Signet Book", 4.55859375, "Night Shift (Signet)", 1979 ], ... ] }

この例では、書籍に関連する 6 つのプロパティ (著者、説明、出版社、評価、タイトル、年) と 10 件の結果 (すべて Stephen King の書籍) があります。

ES|QL でサポートされているすべてのタイプのリストはここに記載されています。

$result応答オブジェクトには、配列、文字列、またはオブジェクトとしてアクセスできます (詳細については、ここを参照してください)。

オブジェクト インターフェイスを使用すると、プロパティとインデックスを使用して値にアクセスできます。たとえば、 $result->values[0][4]リストの最初の本 (0) のタイトル (4) を返し、 $result->values[1][3] 2 番目の本 (1) のランク スコア (3) を返します。PHP の配列のインデックスは 0 から始まることに注意してください。

このインターフェースは、いくつかのユースケースでは十分ですが、ほとんどの場合、結果としてオブジェクトの配列を取得したいと考えます。

結果をオブジェクトの配列にマップするには、elasticsearch-php の新しいmapTo()機能を使用できます。

この関数は、 Elasticsearch レスポンス オブジェクトで直接使用できます。つまり、次のようにアクセスできます。

$books = $result->mapTo(); // Array of stdClass foreach ($books as $book) { printf( "%s, %s, %d, Rating: %.2f\n", $book->author, $book->title, $book->year, $book->rating ); }

カスタム Book クラスがある場合は、次のようにそれを使用して結果をマップできます。

class Book { public string $author; public string $title; public string $description; public int $year; public float $rating; } $books = $result->mapTo(Book::class); // Array of Book

クラスに ES|QL 結果に含まれるプロパティに加えて他のプロパティがある場合も、これは同様に機能します。mapTo()関数は、ES|QL 結果の列として返されるプロパティのみを使用します。

この記事で報告されているすべての例は、ここからダウンロードできます。

]]> https://www.elastic.co/search-labs/blog/esql-php-map-object-class https://www.elastic.co/search-labs/blog/esql-php-map-object-class Mon, 08 Apr 2024 00:00:00 GMT