Introdução ao Elastic Agent Builder e Strands Agents SDK
Aprenda a criar um agente com o Elastic Agent Builder e explore como usar o agente via protocolo A2A orquestrado com o Strands Agents SDK.
Você tem uma ideia para um agente de IA? Provavelmente isso envolve fazer algo com os dados, porque se um agente for iniciar uma ação útil, ele precisa tomar uma decisão e precisa dos dados certos para tomar a decisão certa.
O Elastic Agent Builder facilita a criação de agentes de IA conectados a dados. Mostraremos como fazer isso neste post do blog. Vamos passar por todos os passos necessários para criar um agente com uma ferramenta MCP que acesse os dados armazenados no Elastic. Depois, usaremos o Strands Agents SDK e os recursos Agent2Agent (A2A) para operar o agente. O Strands Agents SDK é uma plataforma de desenvolvimento de IA multiagente que você pode usar para criar apps agentes com código suficiente para garantir o resultado desejado.
Vamos construir um agente de IA que jogue RPS+, uma versão do clássico jogo Pedra, Papel e Tesoura com um diferencial: oferece aos jogadores algumas opções extras.
Pré-requisitos
Aqui está o que é necessário para seguir as etapas deste post do blog:
Um editor de texto rodando no seu computador local
Visual Studio Code é o que usaremos para as instruções de exemplo neste post do blog
Python 3.10 ou superior rodando no seu computador local
Crie um projeto serverless
A primeira coisa de que precisamos é de um projeto Elasticsearch Serverless, que inclua o Elastic Agent Builder.
Acesse cloud.elastic.co e crie um novo projeto Elasticsearch Serverless.
Crie um índice e adicione dados
Em seguida, adicionaremos alguns dados ao nosso projeto Elasticsearch. Abra as Ferramentas de desenvolvedor, onde podemos executar comandos para criar um novo índice e inserir alguns dados. Selecione Ferramentas de desenvolvedor no menu de navegação de nível superior.
Copie e cole o seguinte comando PUT na área de entrada de solicitações do console Ferramentas de desenvolvedor. Essa declaração cria um índice Elasticsearch chamado "game-docs".
PUT /game-docs
{
"mappings": {
"properties": {
"title": { "type": "text" },
"content": {
"type": "text"
},
"filename": { "type": "keyword" },
"last_modified": { "type": "date" }
}
}
}Clique no botão Enviar solicitação que aparece no lado direito da declaração em Ferramentas de desenvolvedor. Você deve ver uma notificação confirmando que o índice game-docs foi criado na área de resposta das Ferramentas de desenvolvedor.
Um índice chamado game-docs é um ótimo lugar para armazenar os dados do jogo que estamos criando. Vamos colocar um documento chamado rps+-md nesse índice que contém todos os dados que nosso jogo requer. Copie e cole o seguinte comando PUT no console Ferramentas de desenvolvedor.
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"
}Clique no botão Enviar solicitação ao lado da declaração para executá-la e adicionar o documento rps+-md ao índice game-docs.
Agora devemos ter alguns dados para consultar e, com o Agent Builder, isso está mais simples do que nunca.
Selecione Agentes no menu de navegação principal.
Agora, é preciso perguntar ao Elastic AI Agent padrão: "Quais dados eu tenho?"
O Elastic AI Agent avalia os dados e retorna uma explicação concisa sobre os dados que possuímos.
Crie uma ferramenta
Ok, agora temos alguns dados no Elastic, vamos utilizá-los. O Agent Builder inclui suporte integrado para criar ferramentas MCP que ajudam os agentes a acessar os dados necessários para ter o contexto correto para a tarefa. Vamos criar uma ferramenta simples que recupere os dados do nosso jogo.
Clique no menu de ações do Agent Builder.
Selecione Ver todas as ferramentas nas opções do menu.
Clique + Nova Ferramenta.
No formulário Criar Ferramenta, selecione ES|QL. Selecione a ferramenta Tipo e insira os valores a seguir.
Para o ID da Ferramenta:
example.get_game_docsPara Descrição:
Get RPS+ doc from Elasticsearch game-docs index.Para Configuração, insira a seguinte consulta na área de texto Mecanismo de consulta ES|QL:
FROM game-docs | WHERE filename == "RPS+.md"O formulário Criar ferramenta que você preencheu deve ter esta aparência: Clique em Salvar para criar a ferramenta.
Temos uma ferramenta nova no suporte de ferramentas. As ferramentas não devem ficar num suporte; elas devem ser usadas. Vamos criar um agente que possa usar nossa nova ferramenta personalizada.
Crie um agente e atribua uma ferramenta a ele.
Criar um agente é muito simples com o Agent Builder. Você só precisa digitar as instruções do agente com alguns detalhes. Vamos criar um agente agora.
Clique no botão Gerenciar agentes.
Clique + Novo agente.
Insira as informações a seguir no formulário Novo Agente.
Para o ID do Agente, insira o texto abaixo:
rps_plus_agentNa área de texto de Instruções personalizadas, insira as seguintes instruções:
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.Para o Nome de exibição, insira o texto abaixo:
RPS+ AgentPara a Descrição de exibição, insira o texto abaixo:
An agent that plays the game RPS+Dê ao agente a ferramenta personalizada que criamos anteriormente, clicando na guia Ferramentas.
Selecione somente a ferramenta example.get_game_docs que criamos anteriormente.
Clique em Salvar para criar o novo agente.
Vamos testar nosso novo agente. Há um link prático para iniciar um bate-papo com qualquer agente da lista de agentes.
Basta digitar “iniciar jogo” e o jogo começará. Funciona!
O agente exibe a escolha de objeto de jogo na parte superior da resposta. Isso é útil porque podemos ver a escolha do agente e confirmar que o jogo está funcionando conforme o esperado. No entanto, saber a escolha do oponente antes de escolher não torna o jogo de Pedra, Papel e Tesoura muito divertido. Para aperfeiçoar e aprimorar o jogo até a forma final, podemos usar uma plataforma de orquestração de agentes que pode controlar agentes com código.
Agora é a hora do Strands Agents SDK.
Strands Agents SDK
Se você tem curiosidade em experimentar novas estruturas de desenvolvimento de agentes, então vale a pena dar uma chance ao Strands Agents SDK. O Strands Agents SDK foi lançado pela AWS (maio de 2025) como uma implementação open source em Python, e agora também existe uma versão em Typescript.
Começando com o Strands Agents SDK em Python
Preparem seus motores de programação, pois agora vamos percorrer o processo de clonagem e execução de um aplicativo de exemplo que usa Strands Agents para controlar o agente RPS+ por meio do protocolo A2A. Vamos criar uma versão aperfeiçoada do jogo RPS+ para que a escolha do agente seja revelada depois que você fizer a sua escolha, pois, afinal, é a adivinhação e o resultado surpreendente que tornam divertidos jogos como o Pedra, Papel e Tesoura.
No seu computador local, abra o Visual Studio Code e abra um novo terminal.
No terminal recém-aberto, execute o seguinte comando para clonar o repositório Elasticsearch Labs:
git clone https://github.com/elastic/elasticsearch-labsExecute o seguinte cd comando para alterar o diretório para o diretório elasticsearch-labs:
cd elasticsearch-labsEm seguida, execute o seguinte comando para abrir o repositório no Visual Studio Code:
code .No Visual Studio File Explorer, expanda as pastas contenting-blog-content e agent-builder-a2a-strands-agents e abra o arquivo elastic_agent_builder_a2a_rps+.py. Veja a aparência do arquivo aberto no Visual Studio Code:
Aqui está o conteúdo de elastic_agent_builder_a2a_rps+.py que você deve ver no seu editor de texto:
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())Vamos revisar o que está acontecendo nesse código. Começando pelo método main(), o código começa acessando as variáveis de ambiente para a URL do agente e a Chave da API. Depois, usamos esses valores para criar um httpx client que podemos usar para obter o cartão de agente para o agente. O cliente então usa os detalhes do cartão do agente para enviar uma solicitação "iniciar jogo" ao agente. Uma coisa interessante a notar aqui é que incluímos um valor random_game_object como parte do pedido "start game". Esse valor é um número aleatório gerado com o módulo aleatório da biblioteca padrão do Python. A razão para fazer isso é que os poderosos LLMs (que possibilitam agentes de IA) não são bons em aleatoriedade. Não tema, Python vem pra salvar.
Continuando com o código, quando o agente responde à solicitação "iniciar jogo", o código remove a seleção de objeto de jogo do agente e a salva na variável agent_choice. O restante da resposta é exibido como texto para o usuário final. Em seguida, o usuário é solicitado a fornecer a entrada da sua escolha de objeto de jogo, que é enviada ao agente. O código então exibe a escolha do objeto de jogo do agente junto com a determinação final do agente sobre o resultado do jogo.
Definindo a URL do seu agente e a chave de API como variáveis de ambiente
Como o app de exemplo estará rodando no seu computador local, para nos comunicarmos com nosso agente Agent Builder, precisamos fornecer ao Strands Agents SDK uma URL A2A e uma chave API para o agente. O exemplo de app usa um arquivo chamado .env para armazenar esses valores.
Faça uma cópia do arquivo env.example e nomeie o novo arquivo como .env
Volte para o Elastic Agent Builder, onde podemos obter os dois valores que precisamos.
Selecione Exibir todas as ferramentas no menu de ação do Agent Builder no canto superior direito da página.
Clique no menu suspenso Servidor MCP na parte superior da página Ferramentas e selecione Copiar URL do Servidor MCP.
Cole o URL do servidor MCP no arquivo .env como um substituto para o valor do espaço reservado <YOUR-ELASTIC-AGENT-BUILDER-URL> . Agora precisamos fazer uma atualização no URL, ou seja, substituir o texto final “mcp” por “a2a”, pois o protocolo A2A é o que o Agent Strands SDK usará para se comunicar com o agente em execução no Elastic Agent Builder.
A URL editada deve ficar assim:
https://rps-game-project-12345a.kb.us-east-1.aws.elastic.cloud/api/agent_builder/a2aOutro valor que precisamos obter enquanto estamos aqui no Elastic Cloud é uma chave API. Clique em Elasticsearch na navegação de nível superior.
Clique no botão Copiar chave API para copiar a chave API.
Agora, de volta ao Visual Studio Code, cole a chave API no .env para substituir o texto provisório <YOUR-ELASTIC-API-KEY> . Seu arquivo .env deve ficar assim:
Execute o app de exemplo
Abra um novo terminal no Visual Studio Code.
Comece executando o seguinte comando cd no terminal:
cd elasticsearch-labs/supporting-blog-content/agent-builder-a2a-strands-agentsExecute o seguinte comando para criar um ambiente virtual Python.
python -m venv .venvDependendo do sistema operacional do seu computador local, execute o seguinte comando para ativar o ambiente virtual.
MacOS/Linux
source .venv/bin/activateWindows
.venv\Scripts\activateO app de exemplo usa o Strands Agents SDK e agora estamos no ponto em que precisamos instalá-lo. Execute o seguinte comando para instalar o Strands Agents SDK junto com todas as dependências necessárias da biblioteca Python.
pip install -r requirements.txtHora de liberar a plataforma de lançamento e começar a contagem regressiva. Estamos prontos para executar este app. Afastem-se. Vamos executá-lo usando o seguinte comando:
python elastic_agent_builder_a2a_rps+.pyVocê deve ser desafiado com uma partida de RPS+. Parabéns e boa sorte!
Crie seus aplicativos de IA com contexto relevante
Construir um Agente de IA agora é uma habilidade disponível na sua caixa de ferramentas. E você já viu como é fácil usar agentes Elastic Agent Builder via A2A em frameworks de desenvolvimento de agentes como o Strands Agents SDK. Experimente a Elastic para criar agentes de IA conectados ao contexto relevante em seus dados personalizados.
