开始使用 Elastic Agent Builder 和 Microsoft Agent Framework

作者：来自 Elastic Jonathan Simon

逐步讲解如何使用 Elastic Agent Builder 创建一个 agent 的完整流程，然后探索如何通过由 Microsoft Agent Framework 编排的 A2A 协议来使用该 agent。

Agent Builder 现在作为技术预览版提供。开始使用 Elastic Cloud 试用，并在此查看 Agent Builder 的文档。

Elastic 9.2 最近发布，并包含一个名为 Agent Builder 的新功能。它让开发者能够快速创建由 Elasticsearch 中存储的数据驱动的 AI agents 和 tools。你在 Agent Builder 中创建的任何 tools 或 agents 都可以立即在你自己的自定义 AI 应用中使用。

在这篇博客文章中，我们将讲解使用 Elastic Agent Builder 创建一个 agent 的所有步骤。然后我们将讲解运行一个示例 Python 应用的流程，该应用使用 Microsoft Agent Framework 来编排你的 Elastic agent。

创建一个 Elastic Serverless 项目

要使用 Agent Builder，你需要一个 Elastic 部署或一个 Elastic serverless 项目，所以我们先从创建一个 Elastic serverless 项目开始。进入 Elastic Cloud 并创建一个新的 Elasticsearch Serverless 项目。

创建一个索引并添加数据

现在我们已经有了一个 Elastic 项目，让我们创建一个索引，这是 Elasticsearch 用来存储数据的地方。打开 Elastic Cloud 中的 Developer Tools，我们可以在这里运行命令来创建一个索引。

复制下面的 PUT 命令，它会创建一个名为 my-docs 的索引，包含多种字段，以及利用语义搜索的内容。

bash 复制代码

`

1.  PUT /my-docs
2.  {
3.    "mappings": {
4.      "properties": {
5.        "title": { "type": "text" },
6.        "content": { 
7.          "type": "semantic_text"
8.        },
9.        "filename": { "type": "keyword" },
10.        "last_modified": { "type": "date" }
11.      }
12.    }
13.  }

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

将 PUT 命令粘贴到 Developer Tools 控制台的输入区域。把鼠标悬停在控制台中的命令上，然后点击 Run 按钮来执行该命令。

下一步是向你刚创建的 my-docs 索引中添加一些数据。将下面的命令复制并粘贴到 Develop Tools 控制台中。

bash 复制代码

`

1.  PUT /my-docs/_doc/greetings-md
2.  {
3.    "title": "Greetings",
4.    "content": "
5.  # Greetings

7.  ## Basic Greeting
8.  Hello!

10.  ## Helloworld Greeting
11.  Hello World! 🌎

13.  ## Not Greeting
14.  I'm only a greeting agent. 🤷

16.  ",
17.    "filename": "greetings.md",
18.    "last_modified": "2025-11-04T12:00:00Z"
19.  }

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

点击该命令的 Run 按钮来执行命令，这将向 my-docs 索引添加一个文档。

如你所见，上面的命令添加了一个名为 greetings.md 的文档，其中包含不同类型的问候回应内容。

现在我们已经在 Elastic 索引中有了一些数据，让我们确认一下可以使用的数据。利用 Agent Builder 中默认启用的内置 Elastic AI Agent，你现在可以就你的数据进行对话。在导航菜单中选择 Agents。

然后只需问："我有什么数据？"

默认的 Elastic AI Agent 会提供当前存储在 Elastic 中数据的良好总结。

创建一个 tool

此演练的下一步是创建一个能够使用存储在 Elastic 中数据的 agent。

如你所见，Elastic Agent Builder 中的默认 agent 已经可以用来与你的数据聊天，但要真正赋予 agent 自定义能力，它们需要通过 Model Context Protocol (MCP) 访问 tools。Agent Builder 拥有完整的 tool 创建和管理功能，你可以用它快速创建自定义 MCP tools，这些 tools 会托管在与数据相同的可扩展 Elastic 项目中。

现在让我们在 Elastic Agent Builder 中创建一个可以访问 Elastic 中数据的 tool。点击 + New 开始。

然后点击 Manage tools。

点击 + New tool 按钮。

在 Create Tool 表单中，选择 ES|QL 作为 tool Type，并输入以下值。

Tool ID：

go 复制代码

`example.get_greetings`AI写代码

Description：

sql 复制代码

`Get greetings doc from Elasticsearch my_docs index.`AI写代码

Configuration：在 ES|QL Query 文本区域中输入以下查询：

ini 复制代码

`FROM my-docs | WHERE filename == "greetings.md"`AI写代码

你完成的 Create a new tool 表单应如下所示。点击 Save 创建该 tool。

创建一个 Agent 并为其分配一个 tool

啊！有了新 tool 并准备使用的感觉真好。Agents 需要 tools 来赋予它们超出一般 LLM 能力的特殊功能，而我们现在有了一个全新的 tool。让我们创建一个可以充分利用我们 tool 的 agent。在导航菜单中选择 Agents。

点击 Create a new agent。

根据 tool 的名称和它访问的数据，你可能已经猜到我们要创建一个问候 agent，你猜对了！让我们现在创建一个 Hello World agent。

在 New Agent 表单中，输入以下值。

Agent ID：输入文本：

go 复制代码

`helloworld_agent`AI写代码

在 Custom Instructions 文本区域中输入以下指令：

sql 复制代码

`

1.  If the prompt contains greeting text like "Hi" or "Hello" then respond with only the Basic Hello text from your documents.

3.  If the prompt contains the text "Hello World" then respond with only the Hello World text from your documents.

5.  In all other cases where the prompt does not contain greeting words, then respond with only the Not Greeting text from your documents.

`AI写代码

Display name：输入文本：

go 复制代码

`HelloWorld Agent`AI写代码

Display description：输入文本：

css 复制代码

`An agent that responds to greetings.`AI写代码

你完成的 New Agent 表单应如下所示。下一步是为 agent 分配我们在上一步创建的 tool。点击 Tools 标签。

只选择我们之前创建的 example.get_greetings tool。取消选择所有其他可用的 tools。这将配置正在创建的 agent 仅能访问我们创建的 tool。

点击 Save 创建该 agent。

你将被带到 Agents 列表，在那里可以看到新的 HelloWorld Agent 已经创建。我们可以在 Agent Builder 中快速测试我们的新 agent。在导航菜单中选择 Agents。

在 Agent Chat agent 选择器中选择 HelloWorld Agent。输入提示 "hello world"，你应该会从存储在 my-docs Elastic 索引中的 greetings.md 文档中得到 Hello World 文本。

干得好。现在我们知道我们的 agent 按预期工作，让我们探索在 Agent Builder 中创建的 tools 和 agents 带来的即时开发好处。你在 Agent Builder 中创建的任何 tools 都可以通过 MCP 被任何支持 MCP 的 agent 构建平台使用。同时，你在 Agent Builder 中创建的任何 agents 都可以在任何支持 AgentToAgent (A2A) 协议的 agent 构建平台中使用。

Microsoft Agent Framework

如果你有兴趣尝试新的 Agent 开发工具，那么最近宣布的开源开发工具包 Microsoft Agent Framework 你绝对应该亲自尝试。Agent Framework 允许你使用 A2A 协议来编排 agent 应用，可以组合在不同主机上运行的多个 agents，从而实现仅靠通用 GenAI Large Language Model 无法实现的解决方案。Agent Framework 提供 Python 和 C# 版本。让我们看看如何使用基于 Python 的 Agent Framework 调用我们刚创建的自定义 Elastic Agent。

在 Python 中开始使用 Agent Framework

让我们运行一些代码！在你的本地电脑上打开 Visual Studio Code 并打开一个新的终端。

在打开的终端中，克隆包含 Elastic Agent Builder A2A 示例应用的 Elastic Search Labs 源代码仓库。

bash 复制代码

`git clone https://github.com/elastic/elasticsearch-labs`AI写代码

在终端中，使用 cd 命令切换目录到 elasticsearch-labs。

bash 复制代码

`cd elasticsearch-labs`AI写代码

在终端中，输入以下命令以在 Visual Studio Code 编辑器中打开当前文件夹。

css 复制代码

`code .`AI写代码

在 Visual Studio 文件资源管理器中，展开 supporting-blog-content 和 agent-builder-a2a-agent-framework 文件夹，然后在文本编辑器中打开名为 elastic_agent_builder_a2a.py 的文件。

这是你在文本编辑器中应该看到的 elastic_agent_builder_a2a.py 的内容：

ini 复制代码

`

1.  import asyncio
2.  from dotenv import load_dotenv
3.  import httpx
4.  import os
5.  from a2a.client import A2ACardResolver
6.  from agent_framework.a2a import A2AAgent

9.  async def main():
10.      load_dotenv()
11.      a2a_agent_host = os.getenv("ES_AGENT_URL")
12.      a2a_agent_key = os.getenv("ES_API_KEY")

14.      print(f"Connection to Elastic A2A agent at: {a2a_agent_host}")

16.      custom_headers = {"Authorization": f"ApiKey {a2a_agent_key}"}

18.      async with httpx.AsyncClient(timeout=60.0, headers=custom_headers) as http_client:
19.          # Resolve the A2A Agent Card
20.          resolver = A2ACardResolver(httpx_client=http_client, base_url=a2a_agent_host)
21.          agent_card = await resolver.get_agent_card(
22.              relative_card_path="/helloworld_agent.json"
23.          )
24.          print(f"Found Agent: {agent_card.name} - {agent_card.description}")

26.          # Use the Agent
27.          agent = A2AAgent(
28.              name=agent_card.name,
29.              description=agent_card.description,
30.              agent_card=agent_card,
31.              url=a2a_agent_host,
32.              http_client=http_client,
33.          )
34.          prompt = input("Enter Greeting >>> ")
35.          print("\nSending message to Elastic A2A agent...")
36.          response = await agent.run(prompt)
37.          print("\nAgent Response:")
38.          for message in response.messages:
39.              print(message.text)

42.  if __name__ == "__main__":
43.      asyncio.run(main())

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

main() 方法中的代码演示了如何使用 Agent Framework 控制你的 Elastic Agent Builder agent。它使用来自你的 Elastic 项目的 URL 和 API key 为 agent 创建一个 http_client。然后调用 Agent Framework 的 A2ACardResolver，并传入该 http_client，以根据 relative_card_path 为 "/helloworld_agent.json" 获取 agent 的 A2A agent card，从而引用你的 agent 的 Agent ID，即 "helloworld_agent"。接着，代码使用 Agent Framework 调用你的 agent 并传入 A2A agent card。main() 方法的最后部分提示应用的用户输入一个 "greeting"，然后将用户输入作为提示发送给你的 agent。根据你创建 agent 时指定的指令和 tools，agent 的响应会显示给应用用户。

将你的 agent URL 和 API Key 设置为环境变量

复制文件 env.example 并将新文件命名为 .env。编辑新创建的 .env 文件，将环境变量的值设置为从你的 Elastic 项目中复制的特定值。

首先，我们将替换为你可以从 Elastic 项目中的 Agent Builder - Tools 页面复制的 Agent URL 路径。回到 Elastic Agent Builder，在导航菜单中点击 Agents。

选择 Manage tools。

点击 Tools 页面顶部的 MCP Server 下拉菜单。选择 Copy MCP Server URL。

回到 Visual Studio Code，在 .env 文件中找到占位符文本 "YOUR-ELASTIC-AGENT-BUILDER-URL>"，并粘贴复制的 MCP Server URL 来替换占位符文本。现在编辑粘贴的 MCP Server URL。删除 URL 末尾的 "mcp" 文本，并替换为 "a2a"。编辑后的 URL 应该看起来像这样：

bash 复制代码

`https://example-project-a123.kb.westus2.azure.elastic.cloud/api/agent_builder/a2a`AI写代码

下一个需要在 .env 文件中替换的占位符文本是。我们将用来自你的 Elastic 项目的实际 API Key 替换它。回到你的 Elastic 项目，在导航菜单中点击 Elasticsearch。

点击 Create API key 创建一个新的 API key。

输入 API key 的 Name，然后点击 Create API key。

点击复制按钮来复制 API key。

回到 Visual Studio Code，在 .env 文件中找到占位符文本 ""，并粘贴复制的 API Key 值来替换占位符文本。

现在我们可以保存对 .env 文件所做的更改。编辑后的文件应看起来像这样：

运行示例应用

现在是运行代码的时候了。为此，在 Visual Studio Code 中打开一个新终端。点击顶部菜单的 Terminal，然后选择 New Terminal。

在新终端中，使用 cd 命令切换目录到包含 agent-builder-a2a-agent-framework 示例应用的目录。

bash 复制代码

`cd elasticsearch-labs/supporting-blog-content/agent-builder-a2a-agent-framework`AI写代码

在终端中，通过运行以下代码创建一个 Python 虚拟环境。

go 复制代码

`python -m venv .venv`AI写代码

在终端窗口中运行以下命令以激活虚拟环境（根据你的操作系统）：

如果你使用的是 MacOS 或 Linux，激活虚拟环境的命令是：

bash 复制代码

`source .venv/bin/activate`AI写代码

如果你使用的是 Windows，激活虚拟环境的命令是：

r 复制代码

`.venv\Scripts\activate`AI写代码

elastic_agent_builder_a2a.py 文件中的代码由 Microsoft Agent Framework 驱动，我们仍然需要安装它，所以现在来安装。运行以下 pip 命令以安装基于 Python 的 Agent Framework 及其所需的 Python 包：

go 复制代码

`pip install -r requirements.txt`AI写代码

太棒了！现在一切都已就绪。是时候体验那种美妙的感觉了......让我们运行它。在终端中输入以下命令运行示例代码：

go 复制代码

`python elastic_agent_builder_a2a.py`AI写代码

你应该会看到 Agent Framework 连接到 Elastic Agent。当提示输入 greeting 时，输入 "hello world"。你应该会看到 HelloWorld Agent 的响应 → Hello World! 🌎

顶尖的工作！

在 Agent Builder 中构建 agents 并将它们连接到 tools，可以让你立即与最新的 agent 开发平台（如 Microsoft Agent Framework）实现可操作性。你现在已经知道如何创建一个 Elastic agent 并将其用作可扩展的相关数据源，随时为你接下来构建的所有 AI 应用提供自定义上下文。

今天就免费试用 Elastic 并创建一些 agents 吧！