Você pode integrar o MongoDB com os Agentes Strands para salvar as sessões de conversação e a memória de longo prazo de um agente em uma implementação do MongoDB. Este tutorial usa o conjunto de ferramentas strains-mongodb. O pacote serve para persistir as sessões do agente e para salvar e pesquisar dados. Em seguida, executa um agente que responde a uma pergunta sobre pinguins usando a memória armazenada no MongoDB.
Neste tutorial, você executa as seguintes tarefa:
Configure seu ambiente.
Salve informações sobre pinguins em um armazenamento em memória e defina uma consulta de pesquisa vetorial no MongoDB que utilize essas informações.
Configure um agente que utilize o MongoDB para sessões e memória.
Execute o arquivo e revise a saída.
Plano de fundo
Strands Agents is AWS's open-source Python SDK for building AI agents. This tutorial uses the following strands-mongodb classes to connect an agent to MongoDB:
MongoDBStorage: Mantém as sessões do agente, os dados de gerenciamento de contexto e as transcrições no MongoDB.MongoDBMemoryStoreSalva informações como documentos na memória do MongoDB e permite pesquisá-las por significado, por palavra-chave ou por ambos.
Por padrão, o MongoDB Vector Search gera os embeddings para as memórias, portanto, você não precisa de um modelo de embedding nem de uma chave de API de provedor de embeddings.
Pré-requisitos
Para concluir este tutorial, você deve ter os seguintes recursos:
Um dos seguintes tipos de cluster MongoDB :
Um cluster do Atlas executando a versão do MongoDB 6.0.11, 7.0.2, ou posterior. Certifique-se de que seu endereço IP esteja incluído na lista de acesso do seu projeto Atlas.
Uma implantação local do Atlas criada usando Python e Docker. Instale
atlas-local-lib-py(pip install atlas-local-lib-py) para criar e gerenciar implantações locais programaticamente. Para saber mais, consulte o repositório atlas-local-lib-py.Um cluster MongoDB Community com Search e pesquisa vetorial instalados.
Uma chave de API da OpenAI. Você deve ter uma conta da OpenAI com créditos disponíveis para solicitações de API. Para aprender mais sobre como registrar uma conta OpenAI, consulte o website de API OpenAI.
Python v3.10 ou posterior.
Configurar o ambiente
Nesta seção, você prepara seu ambiente instalando as dependências necessárias, definindo suas variáveis de ambiente e criando um arquivo de projeto.
Instale as dependências.
A partir do seu diretório strands-mongodb-project, execute o seguinte comando para instalar as dependências necessárias:
uv pip install 'strands-mongodb[all]' 'strands-agents[openai]' python-dotenvThe strands-agents[openai] extra installs the OpenAI model provider that this tutorial uses. To use a different provider, see Model Providers in the Strands Agents documentation.
Defina suas variáveis de ambiente.
In your strands-mongodb-project directory, create an .env file and add the following code:
OPENAI_API_KEY="<openai-api-key>"MONGODB_URI="<connection-string>"Replace <openai-api-key> with your OpenAI API key.
Substitua <connection-string> pela string de conexão do seu cluster do Atlas ou da implantação local do Atlas.
Sua string de conexão deve usar o seguinte formato:
mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.netIMPORTANTE: certifique-se de que a string de conexão inclua as credenciais do usuário de banco de dados. Para aprender mais sobre como localizar sua string de conexão, consulte Conectar-se a um cluster por meio de bibliotecas de clientes.
Sua string de conexão deve usar o seguinte formato:
mongodb://localhost:<port-number>/?directConnection=truePara saber mais, consulte Connection strings.
Crie um arquivo de projeto.
In your strands-mongodb-project directory, create a file named main.py. Add the following code to this file to load your environment variables, import the required modules, and define the --query command-line argument:
import argparseimport asyncioimport os
from dotenv import load_dotenvfrom strands import Agentfrom strands.memory import MemoryManagerfrom strands.models.openai import OpenAIModelfrom strands.session import SnapshotSessionManagerfrom strands_mongodb import MongoDBMemoryStore, MongoDBStoragefrom strands_mongodb.types import MongoDBConfig
load_dotenv()
parser = argparse.ArgumentParser()parser.add_argument("--query", required=True)args = parser.parse_args()Em etapas futuras, você adicionará código a este arquivo para configurar sua conexão com o MongoDB, salvar documentos na memória e criar um agente que acesse esses documentos.
Configure o armazenamento de memória
Nesta seção, você se conecta ao MongoDB, salva informações sobre pinguins em um armazenamento em memória e define uma consulta de pesquisa vetorial do MongoDB que utiliza essas informações.
Configure a conexão com o MongoDB.
Add the following code to your main.py file to create a MongoDBConfig dictionary that accesses the strands_tutorial database:
connection: MongoDBConfig = { "connection_string": os.environ["MONGODB_URI"], "database": "strands_tutorial",}Compartilhe este dicionário com todas as classes que se conectam ao MongoDB para garantir que as classes compartilhem o mesmo pool de conexões.
Crie um espaço de armazenamento de memória gravável.
Add the following code to your main.py file to create a MongoDBMemoryStore instance that saves each memory as a document in the memory collection:
store = MongoDBMemoryStore( name="penguin_facts", config=connection, scope="field-researcher", writable=True,)Este código define os seguintes parâmetros:
name: Identifies the memory store. The store adds a field namedstore_nameto every memory document and sets the field's value to"penguin_facts". The store reads only the memories that hold this value.scopeSepara esses documentos de memória das memórias que outros usuários ou agentes salvam na mesma coleção.writable: Allows the memory store and the agent to save memories. The default value isFalse.
Salve as curiosidades sobre pinguins.
Add the following code to your main.py file to define the program's entry point and save three memory documents, which store penguin facts:
async def main() -> None: await store.add( "Emperor penguins can dive deeper than any other bird," " reaching depths of over 500 meters." ) await store.add( "Gentoo penguins are the fastest underwater swimmers among" " penguins, reaching speeds of up to 36 kilometers per hour." ) await store.add( "Adélie penguins live along the Antarctic coastline." )Pesquise os documentos de memória.
Add the following code to your main() function to search the memory documents. The code prints every memory document that the search returns, ranked by relevance to the --query value.
found = []for _ in range(60): found = await store.search(args.query) if len(found) >= 3: break await asyncio.sleep(5)else: raise SystemExit("The search indexes are not ready. Try again.")
print("Search results:")for entry in found: print(f"- {entry.content}")A pesquisa vetorial do MongoDB gera os embeddings para cada novo documento de memória de forma assíncrona, após a conclusão da operação de gravação. Até que os embeddings estejam prontos, os resultados da sua pesquisa vetorial podem estar incompletos. O código anterior tenta novamente a pesquisa a cada cinco segundos, por até cinco minutos, até retornar todas as três memórias.
Configurar um agente
Nesta seção, você configura um agente que salva suas sessões no MongoDB e usa o armazenamento em memória para responder às perguntas.
Crie o agente.
Add the following code to your main() function to create an agent that uses MongoDB for sessions and memory:
agent = Agent( model=OpenAIModel( client_args={"api_key": os.environ["OPENAI_API_KEY"]}, model_id="gpt-4o", ), storage=storage, session_manager=SnapshotSessionManager( session_id="penguin-research" ), memory_manager=MemoryManager( stores=[store], add_tool_config=True ), callback_handler=None,)Este código passa os seguintes parâmetros:
model: Uses thegpt-4omodel from OpenAI to generate agent responses.storageFornece a infraestrutura que os subsistemas do agente utilizam para salvar dados persistentes.session_manager: Saves the conversation under the specified session ID. Thestorageparameter alone does not persist sessions.memory_manager: Provides the agent with asearch_memorytool. Setting theadd_tool_config parametertoTruealso configures theadd_memorytool for saving new memories.callback_handler: Oculta a saída de streaming do SDK do seu console.
Inicie uma conversa.
Add the following code to your main() function to send the --query value to the agent and print the agent's answer. The code also lists the keys prefixed with session/ to show that the agent saved the session in MongoDB.
result = await agent.invoke_async(args.query)print("\nAgent:", str(result).strip())
print("\nSession keys:")for key in await storage.list("session/"): print(f"- {key}")
await store.close()Then, add the following code after the main() function to run it:
asyncio.run(main())Execute o arquivo
To run the main.py file, run the following command from your strands-mongodb-project directory. Use the --query flag to specify the question that the application sends to the agent:
uv run main.py --query "Which penguin species can dive the deepest?"Se o comando for executado com êxito, a saída se assemelha ao seguinte:
Search results:- Emperor penguins can dive deeper than any other bird, reaching depths of over 500 meters.- Adélie penguins live along the Antarctic coastline.- Gentoo penguins are the fastest underwater swimmers among penguins, reaching speeds of up to 36 kilometers per hour.
Agent: Emperor penguins can dive deeper than any other bird, reaching depths of over 500 meters.
Session keys:- session/penguin-research/scopes/agent/default/snapshots/snapshot_latest.jsonThe agent answered the question by using the documents stored in MongoDB, and it saved the conversation under the penguin-research session ID.
Próximos passos
To learn more about MongoDBStorage, MongoDBMemoryStore, and their full parameter and method reference, see Integrate MongoDB with Strands Agents.
Para saber mais sobre os Agentes Strands, consulte a documentação dos Agentes Strands.