Premiers pas avec Elastic Agent Builder et le SDK Strands Agents
Découvrez comment créer un agent avec Elastic Agent Builder, puis explorez comment utiliser cet agent via le protocole A2A orchestré à l’aide du SDK Strands Agents.
Vous avez une idée d’agent IA ? Cela implique sans doute d’exploiter des données : pour que l’agent exécute une action utile, il doit prendre une décision, et pour cela, il lui faut les bonnes données.
Elastic Agent Builder simplifie la création d’agents IA connectés aux données. Nous vous expliquons comment faire dans cet article de blog. Voici toutes les étapes pour créer un agent avec un outil MCP capable d’accéder aux données stockées dans Elastic. Nous utiliserons ensuite le SDK Strands Agents et ses fonctionnalités Agent2Agent (A2A) pour piloter l’agent. Le SDK Strands Agents est une plateforme de développement d’IA multi-agents, conçue pour créer des applications autonomes avec juste ce qu’il faut de code pour obtenir les résultats souhaités.
Construisons un agent IA capable de jouer à RPS+, une version revisitée du jeu classique « Pierre, feuille, ciseaux », enrichie de quelques choix supplémentaires pour les joueurs.
Produits requis
Voici ce dont vous avez besoin pour suivre les étapes décrites dans cet article de blog :
Un éditeur de texte fonctionnant sur votre ordinateur local
Nous utiliserons Visual Studio Code pour suivre les exemples présentés dans cet article de blog.
Python 3.10 ou version supérieure installé localement sur votre machine
Créez un projet sans serveur
La première étape consiste à créer un projet Elasticsearch Serverless, qui inclut Elastic Agent Builder.
Accédez à cloud.elastic.co et créez un nouveau projet Elasticsearch Serverless.
Créer un index et ajouter des données
Ensuite, nous allons ajouter des données à notre projet Elasticsearch. Ouvrez les Developer Tools pour exécuter des commandes : nous allons créer un nouvel index et y insérer des données. Dans le menu principal, sélectionnez Developer Tools.
Copiez-collez la commande PUT suivante dans la zone de saisie de requêtes de la console Developer Tools. Cette commande crée un index Elasticsearch nommé « game-docs ».
PUT /game-docs
{
"mappings": {
"properties": {
"title": { "type": "text" },
"content": {
"type": "text"
},
"filename": { "type": "keyword" },
"last_modified": { "type": "date" }
}
}
}Cliquez sur le bouton Envoyer la requête à droite de l’instruction dans Developer Tools. Une notification doit confirmer que l’index game-docs a bien été créé, dans la zone de réponse de Developer Tools.
L’index nommé game-docs est l’endroit idéal pour stocker les données du jeu que nous créons. Ajoutons maintenant un document nommé rps++-md dans cet index, contenant toutes les données nécessaires au jeu. Copiez-collez la commande PUT suivante dans la console Developer Tools.
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"
}Cliquez sur le bouton Envoyer la requête à côté de l’instruction pour l’exécuter et ajouter le document rps++-md à l’index game-docs.
Nous avons maintenant des données à interroger, et avec Agent Builder, c’est plus simple que jamais.
Dans le menu de navigation principal, sélectionnez Agents.
Ensuite, il vous suffit de demander à l'agent Elastic AI par défaut, « Quelles données ai-je ? »
L’agent IA Elastic analyse les données et fournit une explication claire des informations disponibles.
Créer un outil
Nous avons maintenant des données dans Elastic, mettons-les à profit. Agent Builder inclut un support natif pour créer des outils MCP, qui permettent aux agents d’accéder aux données dont ils ont besoin pour disposer du bon contexte. Créons un outil simple pour récupérer les données de notre jeu.
Cliquez sur le menu des actions dans Agent Builder.
Dans les options du menu, sélectionnez Afficher tous les outils.
Cliquez sur + Nouvel outil.
Dans le formulaire Créer un outil , sélectionnez ES|QL Saisissez l'outil et entrez les valeurs suivantes.
Pour Tool ID :
example.get_game_docsPour Description :
Get RPS+ doc from Elasticsearch game-docs index.Pour Configuration, saisissez la requête suivante dans la zone de texte ES|QL Query :
FROM game-docs | WHERE filename == "RPS+.md"Le formulaire Créer outil complété devrait ressembler à ceci. Cliquez sur Enregistrer pour créer l'outil.
Un nouvel outil a été ajouté à notre tableau de bord. Les outils ne sont pas faits pour rester inutilisés : ils doivent être mis à profit. Créons un agent qui saura exploiter notre nouvel outil personnalisé.
Créez un agent et attribuez-lui un outil
Créer un agent est d’une simplicité rafraîchissante avec Agent Builder. Il vous suffit de saisir quelques instructions pour l’agent, avec quelques détails : c’est tout. Créons un agent dès maintenant.
Cliquez sur Gérer les agents.
Cliquez + Nouvel agent.
Saisissez les informations suivantes dans le formulaire Nouvel agent.
Pour l'identification de l'agent, saisissez le texte ci-dessous :
rps_plus_agentDans la section texte Instructions personnalisées , saisissez les instructions suivantes :
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.Pour le Nom d'affichage, entrez le texte ci-dessous :
RPS+ AgentPour la Description de l’affichage, saisissez le texte ci-dessous :
An agent that plays the game RPS+Donnez à l'agent l'outil personnalisé que nous avons créé précédemment en cliquant sur l'onglet Outils.
Sélectionnez uniquement example.get_game_docs, l'outil que nous avons créé précédemment.
Cliquez sur Enregistrer pour créer le nouvel agent.
Testons notre nouvel agent. Un lien pratique vous permet de démarrer une conversation avec n’importe quel agent de la liste.
Saisissez simplement « start game » pour lancer la partie. Ça fonctionne !
L’agent affiche son choix pour la partie en haut de sa réponse. Cela permet de visualiser le choix de l’agent et de vérifier que le jeu fonctionne comme prévu. Cela dit, connaître le choix de votre adversaire avant de jouer n’est pas idéal pour une partie de pierre-feuille-ciseaux. Pour peaufiner le jeu, on peut utiliser une plateforme d’orchestration d’agents capable de les piloter via du code.
Le SDK Strands Agents entre en scène.
Strands Agents SDK
Si vous souhaitez essayer de nouveaux frameworks de développement d'agents, le SDK Strands Agents vaut la peine d'être essayé. Le SDK Strands Agents a été publié par AWS (mai 2025) en tant qu'implémentation Python open source, et il existe désormais une version Typescript.
Premiers pas avec le SDK Strands Agents en Python
Lancez vos environnements de développement : nous allons cloner et exécuter une application d’exemple qui utilise Strands Agents pour piloter l’agent RPS+ via le protocole A2A. Créons une version personnalisée du jeu RPS+ dans laquelle le choix de l’agent est révélé après votre propre décision, afin de préserver l’effet de surprise et le côté ludique du jeu Pierre-Feuille-Ciseaux.
Sur votre ordinateur local, ouvrez Visual Studio Code et ouvrez un nouveau terminal.
Dans le terminal que vous venez d’ouvrir, exécutez la commande suivante pour cloner le dépôt Elasticsearch Labs :
git clone https://github.com/elastic/elasticsearch-labsExécution de la commande cd suivante pour changer de répertoire dans le répertoire Elasticsearch Labs :
cd elasticsearch-labsEnsuite, exécutez cette commande pour ouvrir le dépôt dans Visual Studio Code :
code .Dans l'explorateur de fichiers de Visual Studio, développez les dossiers supporting-blog-content et agent-builder-a2a-strands-agents , puis ouvrez le fichier elastic_agent_builder_a2a_rps+.py. Voici à quoi ressemble le fichier ouvert dans Visual Studio Code :
Voici le contenu de elastic_agent_builder_a2a_rps+.py que vous devriez voir dans votre éditeur de texte :
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())Examinons ce qui se passe dans ce code. En commençant par la méthode main() , le code commence par accéder aux variables d’environnement pour l’URL de l’agent et la clé API. Ensuite, nous utilisons ces valeurs pour créer un httpx client que nous pouvons utiliser pour obtenir la carte d'agent de l'agent. Le client utilise ensuite les détails de la carte d’agent pour envoyer une demande de « démarrer la partie » à l’agent. Il est intéressant de noter que nous incluons la valeur random_game_object dans la requête "start game". Cette valeur est un nombre aléatoire généré par le module aléatoire de la bibliothèque standard de Python. La raison pour laquelle nous faisons cela est qu'il s'avère que les puissants LLM (qui rendent possibles les agents IA) ne sont pas très doués pour le hasard. Pas de problème, Python vient à la rescousse.
En poursuivant dans le code, une fois que l’agent a répondu à la requête start game, le code extrait le choix de l’agent et le stocke dans la variable agent_choice. Le reste de la réponse est affiché sous forme de texte à destination de l’utilisateur final. L’utilisateur est ensuite invité à saisir son propre choix d’objet de jeu, qui est envoyé à l’agent. Le code affiche ensuite le choix de l’agent, ainsi que le résultat final du jeu selon l’agent.
Définir l’URL de votre agent et la clé API comme variables d’environnement
Comme l’application d’exemple sera exécutée en local, nous devons fournir au SDK Strands Agents une URL A2A et une clé API pour communiquer avec notre agent. L’application d’exemple utilise un fichier nommé .env pour stocker ces valeurs.
Faites une copie du fichier env.example et nommez le nouveau fichier .env
Retournez dans Elastic Agent Builder pour récupérer les deux valeurs nécessaires.
Sélectionnez Afficher tous les outils dans le menu d'action d'Agent Builder en haut à droite de la page.
Cliquez sur le menu déroulant MCP Server en haut de la page Outils et sélectionnez Copier l’URL MCP Server.
Collez l’URL du serveur MCP dans le fichier .env fichier en remplacement de la valeur d'espace réservé <YOUR-ELASTIC-AGENT-BUILDER-URL> . Nous devons maintenant apporter une modification à l'URL, à savoir remplacer le texte final « mcp » par « a2a », car le protocole A2A est celui que le SDK Agent Strands utilisera pour communiquer avec l'agent exécuté dans Elastic Agent Builder.
L’URL modifiée devrait ressembler à ceci :
https://rps-game-project-12345a.kb.us-east-1.aws.elastic.cloud/api/agent_builder/a2aL'autre valeur dont nous avons besoin d'obtenir pendant que nous sommes ici dans Elastic Cloud est une clé d'API. Cliquez sur Elasticsearch dans la navigation principale.
Cliquez sur le bouton Copier la clé API pour copier la clé API.
Maintenant, de retour dans Visual Studio Code, collez la Clé d'API dans le fichier .env fichier pour remplacer le texte de l'espace réservé <YOUR-ELASTIC-API-KEY> . Votre .env Le fichier devrait ressembler à ceci :
Lancer l’application d’exemple
Ouvrez un nouveau terminal dans Visual Studio Code.
Commencez par exécuter la commande cd suivante dans le terminal :
cd elasticsearch-labs/supporting-blog-content/agent-builder-a2a-strands-agentsExécutez la commande suivante pour créer un environnement virtuel Python.
python -m venv .venvSelon le système d’exploitation de votre machine, exécutez la commande suivante pour activer l’environnement virtuel.
MacOS/Linux
source .venv/bin/activateWindows
.venv\Scripts\activateL’application d’exemple utilise le SDK Strands Agents, et nous arrivons à l’étape où il faut l’installer. Exécutez la commande suivante pour installer le SDK Strands Agents avec toutes ses dépendances Python.
pip install -r requirements.txtIl est temps de dégager la rampe de lancement et de commencer le compte à rebours. Nous sommes prêts à lancer cette application. Reculez un peu. Lançons-la avec la commande suivante :
python elastic_agent_builder_a2a_rps+.pyLe défi ? Une partie de RPS+ vous attend. Bravo et bonne chance pour la suite !
Créez vos applications d'IA avec un contexte pertinent
La création d'un agent IA fait désormais partie de vos compétences. Vous avez vu aussi combien il est facile d'utiliser Elastic Agent Builder via A2A dans des frameworks de développement d'agents comme les SDK Strands Agents. Essayez Elastic pour créer des agents IA connectés au contexte pertinent dans vos données personnalisées.
