Leitfaden zum Agent Builder und Strands Agents SDK

Haben Sie eine Idee für einen KI-Agenten? Wahrscheinlich geht es darum, etwas mit Daten anzufangen, denn wenn ein Agent eine nützliche Aktion auslösen will, muss er eine Entscheidung treffen, und für diese Entscheidung braucht er die richtigen Daten.

Mit dem Elastic Agent Builder können Sie ganz einfach datenverbundene KI-Agenten erstellen. Wie das geht, zeigen wir Ihnen in diesem Blogbeitrag. Lassen Sie uns alle erforderlichen Schritte durchgehen, um einen Agenten mit einem MCP-Tool zu erstellen, der auf in Elastic gespeicherte Daten zugreift. Dann verwenden wir das Strands Agents SDK und seine A2A-Funktionen (Agent2Agent), um den Agenten zu betreiben. Das Strands Agents SDK ist eine Multiagenten-KI-Entwicklungsplattform, mit der Sie agentenbasierte Anwendungen mit genau dem Code erstellen können, der erforderlich ist, um das gewünschte Ergebnis zu erzielen.

Lassen Sie uns einen KI-Agenten entwickeln, der das Spiel RPS+ spielt, eine Variante des klassischen Spiels „Schere, Stein, Papier“ mit einer zusätzlichen Wendung: Es bietet den Spieler:innen einige zusätzliche Auswahlmöglichkeiten.

Voraussetzungen

Folgendes ist erforderlich, um die Schritte in diesem Blogbeitrag zu befolgen:

Ein Texteditor, der auf Ihrem lokalen Computer ausgeführt wird
- Für die Beispielanleitungen in diesem Blogbeitrag verwenden wir Visual Studio Code.
Python 3.10 oder höher, das auf Ihrem lokalen Computer ausgeführt wird

Ein Serverless-Projekt erstellen

Als Erstes benötigen wir ein Elasticsearch Serverless-Projekt, das den Elastic Agent Builder beinhaltet.

Gehen Sie zu Cloud.elastic.co/de/ und erstellen Sie ein neues Elasticsearch Serverless-Projekt.

Einen Index erstellen und Daten hinzufügen

Als Nächstes fügen wir einige Daten zu unserem Elasticsearch-Projekt hinzu. Öffnen Sie die Entwicklertools, wo wir Befehle ausführen können, um einen neuen Index zu erstellen und einige Daten darin einzufügen. Wählen Sie im Hauptmenü „Entwicklungstools“ aus.

Kopieren Sie den folgenden PUT-Befehl und fügen Sie ihn in den Anfrage-Eingangsbereich der Konsole des Entwicklungstools ein. Diese Anweisung erstellt einen Elasticsearch-Index mit dem Namen „game-docs“.

PUT /game-docs
{
  "mappings": {
    "properties": {
      "title": { "type": "text" },
      "content": { 
        "type": "text"
      },
      "filename": { "type": "keyword" },
      "last_modified": { "type": "date" }
    }
  }
}

Klicken Sie auf die Schaltfläche „Anfrage senden“, die in den Entwicklungstools rechts neben der Anweisung angezeigt wird. Sie sollten eine Benachrichtigung sehen, die bestätigt, dass der Game-docs-Index im Reaktion Flächendiagramm der Entwicklungstools erstellt wurde.

Ein Index namens game-docs ist ein großartiger Ort, um die Daten für das Spiel zu speichern, das wir gerade entwickeln. Fügen wir ein Dokument namens rps+-md in diesen Index ein, das alle Daten enthält, die unser Spiel benötigt. Kopieren Sie den folgenden PUT-Befehl und fügen Sie ihn in das Entwicklungstool ein.

PUT /game-docs/_doc/rps+-md
{
  "title": "Rock Paper Scissors +",
  "content": "
# Game Name
RPS+

# Starting Prompt
Let's play RPS+ !
---
What do you choose?

# Game Objects
1. Rock 🪨 👊
2. Paper 📜 🖐
3. Scissors ✄ ✌️
4. Light ☼ 👍
5. Dark Energy ☄ 🫱

# Judgement of Victory
* Rock beats Scissors
  * because rocks break scissors
* Paper beats Rock
  * because paper covers rock
* Scissors beat Paper
  * because scissors cut paper
* Rock beats Light
  * because you can build a rock structure to block out light
* Paper beats Light
  * because knowledge stored in files and paper books helps us understand light
* Light beats Dark Energy
  * because light enables humans to lighten up and laugh in the face of dark energy as it causes the eventual heat death of the universe
* Light beats Scissors
  * because light is needed to use scissors safely
* Dark Energy beats Rock
  * because dark energy rocks more than rocks. It rocks rocks and everything else in its expansion of the universe
* Dark Energy beats Paper
  * because humans, with their knowledge stored in files and paper books, can't explain dark energy 
* Scissors beat Dark Energy
  * because a human running with scissors is darker than dark energy

# Invalid Input
I was hoping for an worthy opponent
  - but alas it appears that time has past
  - but alas there's little time for your todo list when [todo:fix this] is so vast

# Cancel Game
The future belongs to the bold. Goodbye..
",
  "filename": "RPS+.md",
  "last_modified": "2025-11-25T12:00:00Z"
}

Klicken Sie auf die Schaltfläche „Anfrage senden“ neben der Anweisung, um sie auszuführen und das rps+-md-Dokument zum game-docs-Index hinzuzufügen.

Wir sollten jetzt einige Daten abfragen können, und mit Agent Builder ist das einfacher als je zuvor.

Wählen Sie Agenten aus dem Hauptnavigationsmenü aus.

Dann müssen Sie nur noch den standardmäßigen Elastic AI Agent fragen: „Welche Daten habe ich?“

Der Elastic AI Agent bewertet die Daten und liefert eine prägnante Erklärung der vorhandenen Daten.

Ein Tool erstellen

Okay, wir haben jetzt einige Daten in Elastic. Lassen Sie uns diese nutzen. Der Agent Builder bietet integrierte Unterstützung zur Erstellung von MCP-Tools, die Agenten helfen, auf die Daten zuzugreifen, die sie benötigen, um den richtigen Kontext für ihre Aufgabe zu haben. Lassen Sie uns ein einfaches Tool erstellen, das unsere Spieldaten abruft.

Klicken Sie auf das Aktionsmenü des Agent Builders.

Wählen Sie in den Menüoptionen Alle Werkzeuge anzeigenaus.

Klicken Sie auf + Neues Tool.

Wählen Sie im Formular Tool erstellen die Option ES|QL aus. Wählen Sie als Werkzeugtyp die gewünschte Option aus und geben Sie die folgenden Werte ein.

Für die Tool-ID:

example.get_game_docs

Für die Beschreibung:

Get RPS+ doc from Elasticsearch game-docs index.

Für Konfiguration geben Sie die folgende Abfrage in das ES|QL-Abfrage-Textfeld ein:

FROM game-docs | WHERE filename == "RPS+.md"

Ihr ausgefülltes Formular Tool erstellen sollte wie folgt aussehen. Klicken Sie auf Speichern, um das Tool zu erstellen.

Wir haben ein neues Werkzeug am Werkzeugständer hängen. Werkzeuge sollten nicht einfach nur an einem Regal hängen; sie sollten sinnvoll eingesetzt werden. Lassen Sie uns einen Agenten erstellen, der unser neues benutzerdefiniertes Tool verwenden kann.

Einen Agenten erstellen und ihm ein Tool zuweisen

Mit dem Agent Builder ist das Erstellen eines Agenten erfreulich einfach. Sie müssen einfach nur die Agentenanweisungen mit ein paar Details eingeben. Lassen Sie uns jetzt einen Agenten erstellen.

Klicken Sie auf Agenten verwalten.

Klicken Sie + Neuer Agent.

Geben Sie die folgenden Informationen in das Formular Neuer Agent ein.

Geben Sie für die Agenten-ID den folgenden Text ein:

rps_plus_agent

Geben Sie im Textfeld Benutzerdefinierte Anweisungen die folgenden Anweisungen ein:

When prompted, if the prompt contains an integer, then select the corresponding numbered item in the list of "Game Objects" from your documents. Otherwise select a random game object. This is your chosen game object for a single round of the game.

# General Game Rules
* 2 players
    - the user: the person playing the game
    - you: the agent playing the game and serving as the game master
* Each player chooses a game object which will be compared and cause them to tie, win or lose.

# Start the game
1. This is the way each new game always starts. You make the first line of your response only the name of your chosen game object. 

2. The remainder of your response should be the "Starting Prompt" text from your documents and generate a list of "Game Objects" for the person playing the game to choose a game object from.  

# End of Game: The game ends in one of the following three outcomes:
1. Invalid Input: If the player responds with an invalid game object choice, respond with variations of the "Invalid Input" text from your documents and then end the game.

2. Tie: The game ends in a tie if the user chooses the same game object as your game object choice.

3. Win or Lose: The game winner is decided based on the "Judgement of Victory" conditions from your documents. Compare the user's game object choice and your game object choice and determine who chose the winning game object.

# Game conclusion
Respond with a declaration of the winner of the game by outputting the corresponding text in the "Judgement of Victory" section of your documents.

Geben Sie für den Anzeigenamen den folgenden Text ein:

RPS+ Agent

Für die Anzeigebeschreibung geben Sie den untenstehenden Text ein:

An agent that plays the game RPS+

Geben Sie dem Agenten das benutzerdefinierte Tool, das wir zuvor erstellt haben, indem Sie auf den Tab Tools klicken.

Wählen Sie nur das Tool example.get_game_docs aus, das wir zuvor erstellt haben.

Klicken Sie auf Speichern, um den neuen Agenten zu erstellen.

Lassen Sie uns unseren neuen Agenten ausprobieren. Es gibt einen praktischen Link, um einen Chat mit einem beliebigen Agenten aus der Liste der Agenten zu starten.

Geben Sie einfach „start game“ ein und das Spiel beginnt. Es funktioniert!

Sie können sehen, dass der Agent seine Spielobjektauswahl oben in seiner Reaktion anzeigt. Dies ist nützlich, da wir die Wahl des Agenten sehen und bestätigen können, dass das Spiel wie erwartet funktioniert. Wenn man jedoch die Wahl des Gegners kennt, bevor man selbst wählt, wird das Spiel „Schere, Stein, Papier“ nicht besonders unterhaltsam. Um das Spiel zu verfeinern und seine endgültige Form zu erreichen, können wir eine Agenten-Orchestrierungsplattform verwenden, die Agenten mit Code steuern kann.

Hier kommt das Strands Agents SDK ins Spiel.

Strands Agents SDK

Wenn Sie neugierig darauf sind, neue Frameworks für die Agentenentwicklung auszuprobieren, dann ist das Strands Agents SDK einen Versuch wert. Das Strands Agents SDK wurde von AWS (Mai 2025) als Open-Source-Python-Implementierung veröffentlicht, und es gibt jetzt auch eine Typescript-Version.

Erste Schritte mit dem Strands Agents SDK in Python

Starten Sie Ihre Programmiermaschinen. Wir werden jetzt im Eiltempo den Prozess des Klonens und Ausführens einer Beispiel-App durchgehen, die Strands Agents verwendet, um den RPS+ Agent über das A2A-Protokoll zu steuern. Lassen Sie uns eine optimierte Version des RPS+ Spiels entwickeln, bei der die Wahl des Agenten erst nach Ihrer Wahl bekannt gegeben wird, denn schließlich ist es das Rätselraten und der überraschende Ausgang, der Spiele wie „Schere, Stein, Papier“ so unterhaltsam macht.

Öffnen Sie auf Ihrem lokalen Computer Visual Studio Code und öffnen Sie ein neues Terminal.

Im neu geöffneten Terminal führen Sie folgenden Befehl aus, um das Elasticsearch Labs-Repository zu klonen:

git clone https://github.com/elastic/elasticsearch-labs

Führen Sie den folgenden cd-Befehl aus, um das Verzeichnis in das Verzeichnis „elasticsearch-labs“ zu ändern:

cd elasticsearch-labs

Führen Sie anschließend folgenden Befehl aus, um das Repository in Visual Studio Code zu öffnen:

code .

Erweitern Sie im Visual Studio File Explorer die Ordner supporting-blog-content und agent-builder-a2a-strands-agents und öffnen Sie anschließend die Datei elastic_agent_builder_a2a_rps+.py. So sieht die Datei in Visual Studio Code aus:

Hier ist der Inhalt der Datei elastic_agent_builder_a2a_rps+.py, den Sie in Ihrem Texteditor sehen sollten:

import asyncio
from dotenv import load_dotenv
from uuid import uuid4
import httpx
import os
import random
from a2a.client import A2ACardResolver, ClientConfig, ClientFactory
from a2a.types import Message, Part, Role, TextPart

DEFAULT_TIMEOUT = 60  # set request timeout to 1 minute


def create_message(*, role: Role = Role.user, text: str, context_id=None) -> Message:
    return Message(
        kind="message",
        role="user",
        parts=[Part(TextPart(kind="text", text=text))],
        message_id=uuid4().hex,
        context_id=context_id,
    )


async def main():
    load_dotenv()
    a2a_agent_host = os.getenv("ES_AGENT_URL")
    a2a_agent_key = os.getenv("ES_API_KEY")
    custom_headers = {"Authorization": f"ApiKey {a2a_agent_key}"}

    async with httpx.AsyncClient(
        timeout=DEFAULT_TIMEOUT, headers=custom_headers
    ) as httpx_client:
        # Get agent card
        resolver = A2ACardResolver(httpx_client=httpx_client, base_url=a2a_agent_host)
        agent_card = await resolver.get_agent_card(
            relative_card_path="/rps_plus_agent.json"
        )
        # Create client using factory
        config = ClientConfig(
            httpx_client=httpx_client,
            streaming=True,
        )
        factory = ClientFactory(config)
        client = factory.create(agent_card)
        # Use the client to communicate with the agent
        print("\nSending 'start game' message to Elastic A2A agent...")
        random_game_object = random.randint(1, 5)
        msg = create_message(text=f"start with game object {random_game_object}")
        async for event in client.send_message(msg):
            if isinstance(event, Message):
                context_id = event.context_id
                response_complete = event.parts[0].root.text
                # Get agent choice from the first line of the response
                parsed_response = response_complete.split("\n", 1)
                agent_choice = parsed_response[0]
                print(parsed_response[1])
        # User choice sent for game results from the agent
        prompt = input("Your Choice  : ")
        msg = create_message(text=prompt, context_id=context_id)
        async for event in client.send_message(msg):
            if isinstance(event, Message):
                print(f"Agent Choice : {agent_choice}")
                print(event.parts[0].root.text)


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

Lassen Sie uns einen Blick darauf werfen, was in diesem Code passiert. Ausgehend von der Methode main() greift der Code zunächst auf die Umgebungsvariablen für die Agenten-URL und den API-Schlüssel zu. Dann verwenden wir diese Werte, um ein httpx client zu erstellen, mit dem wir die Agentenkarte für den Agenten abrufen können. Der Client verwendet dann die Agentenkartendaten, um eine „Spiel starten“-Anfrage an den Agenten zu senden. Interessant ist hierbei, dass wir einen random_game_object -Wert als Teil der "start game" -Anfrage einfügen. Dieser Wert ist eine Zufallszahl, die mit dem Zufallsmodul der Standardbibliothek von Python generiert wird. Der Grund dafür ist, dass sich herausgestellt hat, dass die leistungsstarken LLMs (die KI-Agenten ermöglichen) nicht besonders gut in Bezug auf Zufälligkeit sind. Kein Problem, hier kann Python helfen.

Im weiteren Verlauf des Codes wird, sobald der Agent auf die Anfrage „Spiel starten“ antwortet, die Spielobjektauswahl des Agenten extrahiert und in der Variable agent_choice gespeichert. Der Rest der Reaktion wird dem:der Nutzer:in als Text angezeigt. Anschließend wird der:die Nutzer:in zur Eingabe der eigenen Spielobjektauswahl aufgefordert. Diese Auswahl wird an den Agenten gesendet. Der Code zeigt dann die Auswahl des Spielobjekts durch den Agenten sowie dessen endgültige Entscheidung über den Spielausgang an.

Einrichten Ihrer Agenten-URL und Ihres API-Schlüssels als Umgebungsvariablen

Da die Beispiel-App auf Ihrem lokalen Computer ausgeführt wird, müssen wir dem Strands Agents SDK eine A2A-URL und einen API-Schlüssel für den Agenten bereitstellen, damit dieser mit unserem Agent Builder-Agenten kommunizieren kann. Die Beispiel-App verwendet eine Datei namens .env, um diese Werte zu speichern.

Erstellen Sie eine Kopie der Datei env.example und benennen Sie die neue Datei .env.

Wechseln Sie zurück zum Elastic Agent Builder, wo wir die beiden benötigten Werte abrufen können.

Wählen Sie im Aktionsmenü des Agent Builders oben rechts auf der Seite die Option Alle Tools anzeigen aus.

Klicken Sie oben auf der Seite „Tools“ auf das Dropdown-Menü MCP-Server und wählen Sie MCP-Server-URL kopieren.

Fügen Sie die MCP-Server-URL als Ersatz für den <YOUR-ELASTIC-AGENT-BUILDER-URL>-Platzhalterwert in die .env-Datei ein. Nun müssen wir eine Aktualisierung an der URL vornehmen, das heißt, den Endtext „mcp“ durch „a2a“ ersetzen, da das A2A-Protokoll dasjenige ist, das das Agent Strands SDK zur Kommunikation mit dem in Elastic Agent Builder ausgeführten Agenten verwenden wird.

Die bearbeitete URL sollte in etwa so aussehen:

https://rps-game-project-12345a.kb.us-east-1.aws.elastic.cloud/api/agent_builder/a2a

Der andere Wert, den wir hier in Elastic Cloud brauchen, ist ein API-Schlüssel. Klicken Sie in der oberen Navigationsebene auf Elasticsearch.

Klicken Sie auf die Schaltfläche API-Schlüssel kopieren, um den API-Schlüssel zu kopieren.

Zurück in Visual Studio Code fügen Sie nun den API-Schlüssel in die .env-Datei ein, um den Platzhaltertext <YOUR-ELASTIC-API-KEY> zu ersetzen. Ihre .env-Datei sollte etwa so aussehen:

Die Beispiel-App ausführen

Öffnen Sie ein neues Terminal in Visual Studio Code.

Führen Sie zunächst den folgenden cd-Befehl im Terminal aus:

cd elasticsearch-labs/supporting-blog-content/agent-builder-a2a-strands-agents

Führen Sie den folgenden Befehl aus, um eine virtuelle Python-Umgebung zu erstellen.

python -m venv .venv

Führen Sie je nach Betriebssystem Ihres lokalen Computers den folgenden Befehl aus, um die virtuelle Umgebung zu aktivieren.

macOS/Linux

source .venv/bin/activate

Windows

.venv\Scripts\activate

Die Beispiel-App verwendet das Strands Agents SDK, und wir sind nun an dem Punkt in dieser Anleitung angelangt, an dem wir es installieren müssen. Führen Sie folgenden Befehl aus, um das Strands Agents SDK zusammen mit allen erforderlichen Python-Bibliotheksabhängigkeiten zu installieren.

pip install -r requirements.txt

Es ist Zeit, die Startrampe freizumachen und den Countdown zu starten. Wir sind bereit, diese App zu starten. Zurücktreten. Führen wir sie mit folgendem Befehl aus:

python elastic_agent_builder_a2a_rps+.py

Sie sollten mit einer Partie RPS+ herausgefordert werden. Gut gemacht und viel Erfolg!

Erstellen Sie Ihre KI-Apps mit relevantem Kontext

Die Entwicklung eines KI-Agenten gehört nun zu Ihren Kernkompetenzen. Und Sie haben gesehen, wie einfach die Verwendung von Elastic Agent Builder-Agenten über A2A in Agenten-Entwicklungs-Frameworks wie dem Strands Agents SDK ist. Testen Sie Elastic, um KI-Agenten zu erstellen, die mit dem relevanten Kontext Ihrer benutzerdefinierten Daten verknüpft sind.

Ready to try this out on your own? Start a free trial.

Want to get Elastic certified? Find out when the next Elasticsearch Engineer training is running!