Puedes integrar MongoDB con Strands Agents para guardar las sesiones de conversación y la memoria a largo plazo de un agente en un despliegue de MongoDB. Este tutorial utiliza el paquete strands-mongodb para persistir las sesiones del agente y para guardar y buscar datos. Luego, ejecuta un agente que responde a una pregunta sobre pingüinos utilizando la memoria almacenada en MongoDB.
En este tutorial, realizará las siguientes tareas:
Configura tu entorno.
Guarda datos de pingüino en un almacén de memoria y define una consulta de búsqueda vectorial de MongoDB que utilice estos datos.
Configure un agente que utilice MongoDB para sesiones y memoria.
Ejecute el archivo y haga una revisión de la salida.
Segundo plano
Agentes de Hilo es el SDK de Python de código abierto de AWS para crear agentes de IA. Este tutorial utiliza las siguientes clases strands-mongodb para conectar un agente a MongoDB:
MongoDBStorage: Persiste las sesiones del agente, los datos de gestión de contexto y las transcripciones en MongoDB.MongoDBMemoryStore: Guarda la información como documentos de memoria en MongoDB y los busca por significado, por palabra clave o por ambos.
Por defecto, MongoDB Vector Search genera las incrustaciones para las memorias, así que no necesitas un modelo de incrustación ni una clave API del proveedor de incrustación.
Requisitos previos
Para completar este tutorial, debes tener los siguientes recursos:
Uno de los siguientes tipos de clúster de MongoDB:
Un clúster de Atlas que ejecute la versión 6.0.11 de MongoDB, 7.0.2, o posterior. Asegúrese de que su dirección IP esté incluida en la lista de acceso de su proyecto Atlas.
Una implementación local de Atlas creada con Python y Docker. Instala
atlas-local-lib-py(pip install atlas-local-lib-py) para crear y gestionar implementaciones locales mediante programación. Para obtener más información, consulta el repositorio atlas-local-lib-py.Un clúster de MongoDB Community con Search y búsqueda vectorial instalados.
Una llave de API de OpenAI. Debes tener una cuenta de OpenAI con créditos disponibles para las solicitudes de API. Para obtener más información sobre cómo registrar una cuenta de OpenAI, consulta el sitio web de la API de OpenAI.
Python v3.10 o posterior.
Configurar el entorno
En esta sección, preparará su entorno instalando las dependencias necesarias, configurando sus variables de entorno y creando un archivo de Proyecto.
Instala las dependencias.
Desde su directorio strands-mongodb-project, ejecute el siguiente comando para instalar las dependencias necesarias:
uv pip install 'strands-mongodb[all]' 'strands-agents[openai]' python-dotenvEl strands-agents[openai] extra instala el proveedor de modelos OpenAI que utiliza este tutorial. Para usar un proveedor diferente, consulte Proveedoresde modelo en la documentación de Agentes de Canales.
Establecer las variables de entorno.
En tu directorio strands-mongodb-project , crea un archivo .env y añade el siguiente código:
OPENAI_API_KEY="<openai-api-key>"MONGODB_URI="<connection-string>"Sustituye <openai-api-key> por tu clave API de OpenAI.
Se debe sustituir <connection-string> por la cadena de conexión del clúster Atlas o de la implementación local de Atlas.
Su cadena de conexión debe usar el siguiente formato:
mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.netIMPORTANTE: Asegúrate de que tu cadena de conexión incluya las credenciales de tu usuario de base de datos. Para obtener más información sobre cómo encontrar tu cadena de conexión, consulta Conectar a un clúster a través de Librerías de clientes.
Su cadena de conexión debe usar el siguiente formato:
mongodb://localhost:<port-number>/?directConnection=truePara obtener más información, consulta Cadenas de conexión.
Cree un archivo de proyecto.
En tu directorio strands-mongodb-project , crea un archivo llamado main.py. Añade el siguiente código a este archivo para cargar tus variables de entorno, importar los módulos requeridos y definir el argumento --query de línea de comandos:
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()En pasos futuros, añades código a este archivo para configurar tu conexión MongoDB, guardar documentos de memoria y crear un agente que acceda a estos documentos.
Configurar el almacén de memoria
En esta sección, te conectas a MongoDB, guardas datos sobre los pingüinos en un almacén de memoria y defines una consulta de búsqueda vectorial de MongoDB que utiliza estos datos.
Configura la conexión de MongoDB.
Añade el siguiente código a tu archivo main.py para crear un diccionario MongoDBConfig que acceda a la base de datos strands_tutorial :
connection: MongoDBConfig = { "connection_string": os.environ["MONGODB_URI"], "database": "strands_tutorial",}Comparte este diccionario con cada clase que se conecte a MongoDB para asegurarte de que las clases compartan un mismo grupo de conexión.
Crea un almacén de memoria escribible.
Añade el siguiente código a tu archivo main.py para crear una instancia MongoDBMemoryStore que guarde cada memoria como un documento en la colección memory :
store = MongoDBMemoryStore( name="penguin_facts", config=connection, scope="field-researcher", writable=True,)Este código establece los siguientes parámetros:
name: Identifica el almacén de memoria. El almacén añade un campo llamadostore_namea cada documento de memoria y establece el valor del campo en"penguin_facts". El almacén solo lee los recuerdos que contienen este valor.scope: Separa estos documentos de memoria de los recuerdos que otros usuarios o agentes guardan en la misma colección.writable: Permite que el almacén de memoria y el agente guarden memorias. El valor predeterminado esFalse.
Guarda los datos sobre los pingüinos.
Añade el siguiente código a tu archivo main.py para definir el punto de entrada del programa y guardar tres documentos de memoria, que almacenan datos sobre pingüinos:
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." )Busca en los documentos de memoria.
Añade el siguiente código a tu función main() para buscar en los documentos de memoria. El código imprime cada documento de memoria que devuelve la búsqueda, ordenado según su relevancia respecto al valor --query .
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}")MongoDB Vector Search genera las incrustaciones para cada nuevo documento de memoria de forma asíncrona, una vez completada la operación de escritura. Hasta que las incrustaciones estén listas, los resultados de tu búsqueda vectorial pueden estar incompletos. El código anterior intenta la búsqueda de nuevo cada cinco segundos, durante un máximo de cinco minutos, hasta que devuelve las tres memorias.
Configurar un agente
En esta sección, configuras un agente que guarda sus sesiones en MongoDB y utiliza el almacén de memoria para responder preguntas.
Crea el agente.
Añade el siguiente código a su función main() para crear un agente que use MongoDB para sesiones y memoria:
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 pasa los siguientes parámetros:
model: Utiliza el modelogpt-4ode OpenAI para generar respuestas de agentes.storage: Proporciona el backend que los subsistemas del agente utilizan para guardar datos persistentes.session_manager: Guarda la conversación bajo el ID de sesión especificado. El parámetrostoragepor sí solo no persiste las sesiones.memory_manager: Proporciona al agente una herramientasearch_memory. Configurar laadd_tool_config parameterenTruetambién configura la herramientaadd_memorypara guardar nuevos recuerdos.callback_handler: Oculta la salida de streaming del SDK desde tu consola.
Inicia un giro de conversación.
Añade el siguiente código a la función de main() para enviar el valor --query al agente e imprimir la respuesta del agente. El código también lista las claves precedidas con session/ para mostrar que el agente guardó la sesión en 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()Luego, añade el siguiente código después de la función main() para ejecutarlo:
asyncio.run(main())Ejecutar el archivo
Para ejecutar el archivo main.py , ejecute el siguiente comando desde su directorio strands-mongodb-project . Use la bandera --query para especificar la pregunta que la aplicación envía al agente:
uv run main.py --query "Which penguin species can dive the deepest?"Si el comando se ejecuta correctamente, el resultado se parecerá al siguiente:
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.jsonEl agente respondió a la pregunta usando los documentos almacenados en MongoDB y guardó la conversación bajo el ID de sesión penguin-research .
Próximos pasos
Para obtener más información sobre MongoDBStorage, MongoDBMemoryStore, y su referencia completa de parámetros y métodos, consulte Integrar MongoDB con Agentes de Hilos.
Para obtener más información sobre los Agentes de Hilos, consulte la documentación de Agentes de Hilos.