Alibaba Cloud ES Agent Builder-Elasticsearch(ES)-阿里云帮助中心

Agent Builder is a feature provided by Elastic for building intelligent agents. It allows you to retrieve, analyze, and interact with data in Elasticsearch using a large language model (LLM). With Agent Builder, you can quickly build intelligent assistants for business scenarios, such as operations Q&A assistants, log analysis assistants, security analysis assistants, and knowledge base assistants.

Official documentation: Elastic Agent Builder.

Create an agent

The following steps describe how to create and test an agent in Kibana based on OpenSearch for AI.

Log in to the Alibaba Cloud Elasticsearch console.
Note
You need an Elasticsearch instance of version 9.3.2 or later. If you do not have one, see Create an Alibaba Cloud Elasticsearch instance.
The service types available when you create a connector depend on the instance version. Version 9.3.2 supports only OpenAI, whereas versions 9.4 and later also support AlibabaCloud AI Search, whose connector fields are described in Use the AlibabaCloud AI Search service to create a connector in this topic.
Go to Elasticsearch Clusters and click your target instance.
Click Configuration and Management > Data Visualization.
In the Kibana section, click Modify Configuration and ensure an IP address has been added to the public access whitelist. For more information, see Quick start.
Return to the Visualization Control page, click Public Endpoint, enter your username and password, and click Log In to open the Kibana page.
Note
If you forget your password, see Reset instance access password.
In the upper-left corner, click the menu icon and navigate to Elasticsearch > Agents.
Note
The name of this navigation entry changes with the Kibana interface language: it is displayed as Agents in the English interface and as the Chinese equivalent in the Chinese interface. The AI Assistant entry in the upper-right corner of the page also opens this page.
Click Connectors to go to the connector management page.
Click Create connector, select AI Connector, and configure the following settings:
- Connector name: Enter a custom name.
- Service type: Select OpenAI.
  Note
  The OpenSearch for AI large language model API is compatible with the OpenAI API definition. For more information, see Content generation service.
- Model ID: Enter the model name. Because Task type in Additional settings must be set to chat_completion, enter a model whose model category is also chat_completion, such as qwen-turbo, qwen-max, or qwen-plus. The category of each model is listed in Supported services list, and can also be viewed on the AI Service Center > Model Management page of the instance console. The qwen3-max model can also be used, whereas the ops-qwen-turbo model is not currently supported for AI assistants.
  Expand More options and enter the model service endpoint in the URL field, in the format http://{model service endpoint}/compatible-mode/v1/chat/completions. Copy the endpoint from Model Service Endpoint on the AI Service Center > Model Management page of the instance console.
- API Key: In the instance console, go to AI Service Center > Model Management and copy the string that follows API Key for Model Calls.
- Additional settings: Set Task type to chat_completion. This value must match the model category of the model that you specified in Model ID.
Note
Both the model service endpoint and the API key for model calls are available on the AI Service Center > Model Management page of the instance console. After an Elasticsearch instance of version 8.15 or later is created, the AI search platform is enabled automatically, together with a default model service workspace, an API key for model calls, and a model service endpoint. The models themselves must be created manually on that page: a model that has not been created is displayed as (Model not created), and clicking Create Model for that model creates it.
Click Save and test. The page displays three steps in sequence: Create action, Run test, and Result. The connector is successfully created and tested when the Result area shows "The connector ran successfully during the test" and a "Created 'xxx'" message appears at the bottom.
After creating the connector, return to the connector management page. The new AI Connector will appear in the connector list.
Return to the Elasticsearch > Agents page and refresh it.
The agent is created successfully when the page displays a "How can I help you?" chat interface, with the connector and Elastic AI Agent shown at the bottom.

Use the AlibabaCloud AI Search service to create a connector

For instances of version 9.4 or later, the Service type of an AI Connector can be set to AlibabaCloud AI Search in addition to OpenAI; version 9.3.2 supports only OpenAI. The connector fields of this service type map one to one to the information on the AI Service Center > Model Management page of the instance console, so the model service address does not need to be assembled manually.

The AlibabaCloud AI Search service type supports only the qwen-turbo, qwen-max, and qwen-plus models. With any other model, the response structure does not comply with the OpenAI specification, and the agent returns a Required [choices] error when it calls a built-in tool.

Configure the connector fields as follows:

Connector field	Required	Description
Workspace	Yes	The name of the model service workspace, for example, `default`.
Project ID	Yes	The service ID of the model. Only `qwen-turbo`, `qwen-max`, and `qwen-plus` are supported.
Host	Yes	The model service endpoint. Copy the endpoint from the console as it is displayed; no path needs to be appended.
API Key	Yes	The API key for model calls.
Task type	Yes	Select `chat_completion` in Additional settings. The available task types are `text_embedding`, `sparse_embedding`, `rerank`, `completion`, `chat_completion`, `multi_modal_embedding`, `doc_split`, `doc_analyze`, `img_analyze`, and `query_analyze`.
HTTP Schema	No	Default value: `https`.
Rate Limit	No	The rate limit for model calls, set as required.

Important

HTTP Schema must be explicitly set to http. The default value of this field is https, whereas the model service endpoint provided by the console is a private endpoint in the form of default-xxxx.platform-cn-hangzhou-vpc.opensearch.aliyuncs.com, which is usually accessed over HTTP. This is also why the URL requires the http:// prefix when the OpenAI service type is used.

The remaining operations are the same as steps 9 and 10 in Create an agent: click Save and test to create the connector, and then refresh the Agents page to start using it.

Usage example

After creating the agent, you can interact with your Elasticsearch data using natural language. The agent calls a built-in tool that translates natural language into an ES|QL query to analyze data in your Elasticsearch instance.

For example, if your Elasticsearch cluster contains an index with historical API access log data, you can enter "Analyze historical requests to find the slowest API endpoint" in the chat box. The agent performs the following inference process:

Calls a built-in tool (for example, platform.core.search) to identify the relevant data source.
Locates the target index (for example, api_access_logs).
Automatically generates an ES|QL query to group the log data by API name and calculate the average response time, maximum response time, and request count.

The agent returns the analysis results, which include:

Detailed information about the slowest request, such as API name, request path, duration, and status code.
Performance statistics for each API, such as average duration, maximum duration, and request count, visualized as a bar chart.
Performance optimization suggestions, such as where to start troubleshooting slow APIs.

If the agent returns a Required [choices] error when it calls a built-in tool, the model response is missing the choices field required by the OpenAI specification. Check the connector configuration in the following order:

Whether Task type of the connector is chat_completion.
If the OpenAI service type is used, whether the model category of the model specified in Model ID is chat_completion.
If the AlibabaCloud AI Search service type is used, whether Project ID is qwen-turbo, qwen-max, or qwen-plus.