阿里云 ES Agent Builder 使用指引-检索分析服务 Elasticsearch版(ES)-阿里云帮助中心

Agent Builder 是 Elastic 提供的智能代理构建能力，支持基于大语言模型（LLM）和 Elasticsearch 数据进行检索、分析和交互。通过 Agent Builder，可以快速构建面向业务场景的智能助手，例如运维问答助手、日志分析助手、安全分析助手和知识库助手等。

官方文档：Elastic Agent Builder。

创建Agent

以下步骤说明如何在 Kibana 中创建基于 AI搜索开放平台的 Agent 并进行测试。

登录阿里云Elasticsearch管理控制台。
说明
Agent Builder 要求 ES 实例版本为 9.3.2 及以上。如未创建，请参见创建阿里云Elasticsearch实例。
创建连接器时可选的服务类型与版本相关：9.3.2 版本需选择 OpenAI；9.4 及以上版本还可选择 AlibabaCloud AI Search，详情请参见本文使用AlibabaCloud AI Search服务创建连接器。
单击Elasticsearch实例，单击目标实例。
单击 配置与管理 > 可视化控制。
单击Kibana的修改配置，确认已添加 Kibana 公网访问白名单。如未添加，请先增加白名单，详情请参见快速入门。
返回可视化控制页面，单击公网入口，输入用户名、密码，单击登录，进入Kibana页面。
说明
如忘记密码，请参见重置实例访问密码。
单击左上角菜单图标，展开导航栏，单击Elasticsearch > 代理。
说明
导航栏名称随 Kibana 界面语言变化：中文界面显示为代理，英文界面显示为Agents。页面右上角的AI 代理也可进入该页面。
单击连接器，跳转到连接器管理页面。
单击创建连接器，选择AI Connector，按照以下说明填写连接器信息：
- Connector name：自定义名称。
- 服务类型：选择 OpenAI。
  说明
  AI搜索开放平台的大模型接口兼容 OpenAI 接口定义，详情请参见内容生成服务。
- Model ID：输入模型名称。由于后续 Additional settings 中的任务类型需选择 chat_completion，此处需填写模型类别为 chat_completion 的模型，例如 qwen-turbo、qwen-max、qwen-plus。各模型支持的类别请参见支持的服务列表，也可在实例控制台的AI服务中心 > 模型服务页面查看。
  展开 More options，在 URL 处填写模型服务地址，格式为：http://{模型服务接入地址}/compatible-mode/v1/chat/completions。模型服务接入地址从AI服务中心 > 模型服务页面的模型服务接入地址复制。
- API Key：在实例控制台，单击AI服务中心 > 模型服务，复制模型调用API Key后的字符串。
- Additional settings：Task type 选择 chat_completion，且需与上述 Model ID 所属的模型类别一致。
说明
模型服务接入地址和 API Key 均可在实例控制台的AI服务中心 > 模型服务页面获取。创建 ES 8.15 及以上版本实例后，系统会自动开通 AI搜索开放平台并生成默认的模型服务空间、模型调用 API Key 和模型服务接入地址；具体模型需要在该页面手动创建——未创建的模型显示为“(模型未创建)”，单击对应模型的创建模型即可创建。详情请参见AI搜索开放平台。
单击保存并测试。页面依次显示创建操作、运行测试、结果三个步骤，当结果区域提示"执行测试时，连接器运行成功"且底部出现"已创建 'xxx'"时，表示连接器创建并测试通过。
创建成功后，返回连接器管理页面，连接器列表中会显示新创建的 AI Connector 类型连接器。
回到 Elasticsearch > 代理页面，刷新页面，页面显示：
"How can I help you?"对话界面，底部展示已连接的 Connector 和 Elastic AI Agent，表示 Agent 已创建完成。

使用AlibabaCloud AI Search服务创建连接器

ES 9.4 及以上版本的实例，创建 AI Connector 时，服务类型除 OpenAI 外还支持 AlibabaCloud AI Search；9.3.2 版本仅支持 OpenAI。该方式的字段与实例控制台AI服务中心 > 模型服务页面的信息一一对应，无需手工拼接模型服务地址。

重要

AlibabaCloud AI Search 服务类型仅支持 qwen-turbo、qwen-max、qwen-plus 三种模型。使用其他模型时，模型返回结构不符合 OpenAI 规范，Agent 调用内置工具时会报 Required [choices] 错误。

连接器字段的填写说明如下：

连接器字段	是否必填	取值说明
Workspace	是	模型服务空间名称，例如 `default`。
Project ID	是	模型的服务 ID，仅支持 `qwen-turbo`、`qwen-max`、`qwen-plus`。
Host	是	模型服务接入地址，直接复制页面上的地址，无需拼接路径。
API Key	是	模型调用 API Key。
任务类型	是	在其他设置中选择 `chat_completion`。可选任务类型共 10 项：`text_embedding`、`sparse_embedding`、`rerank`、`completion`、`chat_completion`、`multi_modal_embedding`、`doc_split`、`doc_analyze`、`img_analyze`、`query_analyze`。
HTTP Schema	否	默认为 `https`。
Rate Limit	否	按需设置调用速率限制。

重要

HTTP Schema 需显式设置为 http。该字段默认值为 https，而控制台提供的模型服务接入地址是私网地址（形如 default-xxxx.platform-cn-hangzhou-vpc.opensearch.aliyuncs.com），通常需要以 HTTP 访问。这也是使用 OpenAI 服务类型时 URL 需要填写 http:// 前缀的原因。

其余操作与本文创建Agent中的步骤 9 和步骤 10 相同：单击保存并测试创建连接器，然后在代理页面刷新即可使用。

使用示例

Agent 创建完成后，可以通过自然语言与 Elasticsearch 数据交互。Agent 会调用内置工具将自然语言翻译为 ES|QL 查询语句，查询 ES 实例中的数据并进行分析。

例如，当 Elasticsearch 集群中有索引存储了 API 的历史访问日志数据时，在对话框中输入"分析一下历史请求，找出最慢的API接口"。Agent 会执行以下推理过程：

调用内置工具（如 platform.core.search）识别相关数据源。
定位到目标索引（如 api_access_logs）。
自动生成 ES|QL 查询语句，对日志数据按 API 名称分组统计平均响应时间、最大响应时间和请求次数。

Agent 返回分析结果，包括：

最慢请求的详细信息（API 名称、请求路径、耗时、状态码等）。
各 API 的性能统计数据（平均耗时、最大耗时、请求次数），并以柱状图形式可视化展示。
性能优化建议（如针对慢查询 API 的排查方向）。

如果 Agent 调用内置工具时返回 Required [choices] 错误，说明模型返回体缺少 OpenAI 规范要求的 choices 字段，请按以下方向排查连接器配置：

连接器的任务类型是否为 chat_completion。
使用 OpenAI 服务类型时，Model ID 对应的模型类别是否为 chat_completion。
使用 AlibabaCloud AI Search 服务类型时，Project ID 是否为 qwen-turbo、qwen-max、qwen-plus 之一。