Puedes integrar MongoDB con Strands Agents, un SDK de Python de código abierto para construir agentes de IA. El paquete strands-mongodb te permite usar un despliegue de MongoDB como backend para las siguientes clases:
MongoDBStorage, que conserva las sesiones del agente, la gestión de contexto y las transcripciones en MongoDB.
MongoDBMemoryStore, que guarda y recuerda hechos por significado semántico, palabra clave o una combinación de ambos.
Empezar
Para completar un tutorial que configura los Agentes de Hilos para usar MongoDB, consulte Introducción con la integración de Agentes de Hilos de MongoDB.
Instalación
Para instalar el paquete strands-mongodb y las dependencias de las clases MongoDBStorage y MongoDBMemoryStore , ejecute el siguiente comando:
pip install 'strands-mongodb[all]'Este comando instala las siguientes dependencias:
strands-mongodb: El paquete de integración MongoDB para Agentes de Hilos.strands-agents: El SDK de Agentes de Hilos. El paquete requiere v1.54 o posterior.pymongo: El controlador oficial de Python para MongoDB. El paquete requiere v4.14 o posterior.pymongo-search-utils: Utilidades para trabajar con las funciones de búsqueda vectorial de MongoDB. El paquete requiere v0.3 o posterior.opentelemetry-api: La API OpenTelemetry para Python. El paquete requiere v1.30 o posterior.typing-extensions: Funciones de tipado retroportadas para Python. El paquete requiere v4.13.2 o posterior.
Alternativamente, instala las dependencias de clases individuales ejecutando uno de los siguientes comandos:
pip install 'strands-mongodb[storage]' # MongoDBStoragepip install 'strands-mongodb[memory]' # MongoDBMemoryStoreUso
Para configurar tu conexión MongoDB, pasa un diccionario MongoDBConfig a la clase MongoDBStorage o MongoDBMemoryStore . Crea un diccionario MongoDBConfig por proceso y pásalo a cada clase que uses, lo que les permite compartir un solo grupo de conexión.
Puedes especificar un cliente existente o una cadena de conexión para configurar tu conexión. Selecciona la pestaña Existing client o Connection string para ver un ejemplo correspondiente:
from pymongo import AsyncMongoClientfrom strands_mongodb.types import MongoDBConfig
client = AsyncMongoClient("<connection-string>")connection: MongoDBConfig = { "client": client, "database": "agents",}Nota
El paquete no asume la propiedad del cliente. Tú eres responsable de cerrarlo.
Para obtener más información sobre AsyncMongoClient, consulte Crear un MongoCliente.
from strands_mongodb.types import MongoDBConfig
connection: MongoDBConfig = { "connection_string": "<connection-string>", "database": "agents",}Para aprender más sobre cómo encontrar tu cadena de conexión, consulta Conéctate a un clúster mediante librerías de clientes.
MongoDBStorage
La clase MongoDBStorage te permite guardar los datos persistentes de un agente en MongoDB. Una vez configurado, el SDK almacena las sesiones del agente, los datos de gestión de contexto y las transcripciones como documentos en una colección de MongoDB en lugar de en archivos locales o memoria. Los datos persistentes se almacenan bajo claves de cadena y cada clave se convierte en el valor _id de un documento. Como resultado, las operaciones de lectura y escritura realizan consultas por clave primaria.
Esta sección describe cómo configurar y utilizar los métodos proporcionados por la clase MongoDBStorage .
Configuración
Para configurar esta clase, pasa un diccionario MongoDBConfig y un nombre de colección al constructor MongoDBStorage . El siguiente ejemplo escribe datos persistentes en MongoDB, recupera estos datos, lista las claves que comienzan con un prefijo especificado y elimina los datos:
import asyncio
from strands_mongodb import MongoDBStorage
async def main() -> None: storage = MongoDBStorage(connection, collection="storage") try: await storage.write("notes/colony", b"emperor penguins live in Antarctica") print(await storage.read("notes/colony")) print(await storage.list("notes/")) await storage.delete("notes/colony") finally: await storage.close()
asyncio.run(main())Para aprender cómo configurar un agente para usar esta clase, consulte Configurar un agente.
Métodos
La siguiente tabla enumera los métodos proporcionados por la clase MongoDBStorage :
Método | Descripción | Parámetros | Valor de retorno |
|---|---|---|---|
| Almacena datos persistentes como bytes en una clave, reemplazando cualquier valor existente. Si configuras |
|
|
| Devuelve los bytes almacenados en una clave. |
|
|
| Elimina una clave. Si eliminas una clave que no existe, este método no genera ningún error. |
|
|
| Devuelve los nombres de las claves que comienzan con un prefijo, en orden ascendente. Devuelve solo las claves, no los valores almacenados. |
|
|
| Por defecto, este método clasifica los nombres clave almacenados según cuántas palabras comparten con una consulta. Para buscar en los valores almacenados, configura el parámetro |
|
|
| Elimina todas las teclas que comienzan con un prefijo especificado. |
|
|
| Devuelve un nuevo |
|
|
| Crea o verifica el índice TTL que | Ninguno |
|
| Libera el grupo de conexiones para cada instancia que comparte el mismo diccionario | Ninguno |
|
Cuando pasas una instancia MongoDBStorage a un Agent, los subsistemas de sesión y contexto del agente llaman write(), read(), delete(), list()y search() por ti. Llamas a ensure_indexes(), close(), namespace(), y delete_prefix() ti mismo.
MongoDBMemoryStore
La clase MongoDBMemoryStore permite guardar la memoria a largo plazo de un agente en MongoDB. Una vez configurada, el agente almacena datos en una colección de MongoDB y los recupera por significado, por palabra clave o por ambos. La tienda utiliza MongoDB Vector Search para la recuperación semántica y MongoDB Search para la recuperación de palabras clave.
Para usar MongoDB Vector Search, MongoDB compara las incrustaciones vectoriales de tus datos con las incrustaciones de la consulta. Por defecto, MongoDB genera estas incrustaciones por ti, así que no necesitas gestionar vectores ni incrustar claves API del proveedor.
Esta sección describe cómo configurar y utilizar los métodos proporcionados por la clase MongoDBMemoryStore .
Configuración
Para configurar esta clase, pasa un nombre y un diccionario de MongoDBConfig al constructor MongoDBMemoryStore .
Este ejemplo crea un almacén de memoria, añade una memoria y luego busca la memoria por significado semántico. Al instanciar un MongoDBMemoryStore, el ejemplo también establece los siguientes parámetros opcionales:
scope: Limita el acceso del almacén de memoria a documentos que almacenan el valor especificado descopecampo. El ejemplo utiliza el ámbito"user-abc".writable: Activa las operaciones de escritura en el almacén de memoria.
import asyncio
from strands_mongodb import MongoDBMemoryStore
async def main() -> None: store = MongoDBMemoryStore( name="preferences", config=connection, scope="user-abc", writable=True ) try: await store.add("Studies emperor penguins in Antarctica.")
results = await store.search("Which animals does this researcher observe?") for entry in results: print(f"search type: {entry.metadata['_search_type']}") print(f"score: {entry.metadata['_relevance_score']}") print(f"content: {entry.content}") finally: await store.close()
asyncio.run(main())Tipos de búsqueda
MongoDBMemoryStore utiliza los siguientes tipos de búsqueda para responder a una consulta:
Búsqueda vectorial, que coincide por significado.
Búsqueda de texto, que coincide por palabra clave.
Búsqueda híbrida, que combina ambos tipos de búsqueda.
La tecla search_type en el diccionario MongoDBConfig controla qué tipos de búsqueda utiliza la almacén. El valor predeterminado, "auto", prepara cada tipo de búsqueda que soporta la implementación y prefiere el más alto disponible.
Dado que este despliegue prepara ambos índices, un valor search_type de "auto" utiliza la búsqueda híbrida. La búsqueda híbrida clasifica los resultados de forma diferente a la búsqueda vectorial, por lo que las puntuaciones de ambos no son directamente comparables. Un valor min_score o max_score que configuraste para la búsqueda vectorial puede excluir resultados que esperas conservar.
Para aprender cómo configurar un agente para usar esta clase, consulte Configurar un agente.
Métodos
La siguiente tabla enumera los métodos proporcionados por la clase MongoDBMemoryStore :
Método | Descripción | Parámetros | Valor de retorno |
|---|---|---|---|
| Almacena una memoria en el ámbito de este almacén. Las escrituras se desduplican por alcance, nombre de la tienda y contenido, por lo que añadir el mismo dato de nuevo no crea un segundo documento. |
|
|
| Devuelve las memorias que mejor coinciden con una consulta en orden de relevancia. Acepta una cadena simple o un diccionario |
|
|
| Identifica qué características de búsqueda soporta el despliegue y luego crea los índices de este almacén. Este método es llamado automáticamente por | Ninguno |
|
| Elimina una memoria, identificada por la |
|
|
| Elimina toda memoria que este almacén pueda leer. Para utilizar este método, debes establecer | Ninguno |
|
| Libera el grupo de conexiones para cada instancia que comparte el mismo diccionario | Ninguno |
|
Cuando registras esta tienda con MemoryManager, el agente llama a initialize(), search(), y, cuando lo habilitas, add(). Llamas a delete(), delete_all(), y close() ti mismo, porque la interfaz MemoryStore del SDK no tiene métodos de eliminación ni de conexión.
Configurar un agente
Puede configurar un agente para almacenar sus sesiones y memoria a largo plazo en la misma implementación de MongoDB. Esta configuración permite al agente guardar y recuperar esos datos automáticamente mientras se ejecuta.
Para configurar el agente, pasa un diccionario MongoDBConfig tanto al constructor MongoDBStorage como al constructor MongoDBMemoryStore , y luego pasa las instancias resultantes al constructor Agent .
El siguiente ejemplo crea un agente que utiliza MongoDB tanto para sesiones como para memoria:
from strands import Agentfrom strands.memory import MemoryManagerfrom strands.session import SnapshotSessionManagerfrom strands_mongodb import MongoDBStorage, MongoDBMemoryStore
store = MongoDBMemoryStore( name="preferences", config=connection, scope="user-abc", writable=True,)
agent = Agent( model=your_model, storage=MongoDBStorage(connection), session_manager=SnapshotSessionManager(session_id="support-ticket-4127"), memory_manager=MemoryManager(stores=[store], add_tool_config=True),)Se aplican las siguientes consideraciones:
Para permitir que el agente guarde recuerdos, configure la tecla
writableenTrue.La clase
MemoryManagersiempre proporciona al modelo una herramientasearch_memory, pero solo proporciona una herramientaadd_memorycuandoadd_tool_configestá configurada enTrue. Si quieres que el modelo decida cuándo guardar una memoria, activa el parámetroadd_tool_config.El parámetro
add_tool_configgenera unValueErrorsi ninguna tienda que pases es escribible.El parámetro
storagepor sí solo no mantiene las sesiones persistentes. Debes configurarsession_managerpara guardar las sesiones bajo el valor desession_idespecificado.
índice de búsqueda
MongoDBMemoryStore Crea dos índices de búsqueda en el primer uso, a menos que configures la tecla ensure_indexes en False.
El índice de búsqueda vectorial de MongoDB se nombra por la clave de vector_index_name del diccionario MongoDBConfig y tiene la siguiente definición:
{ "fields": [ { "type": "autoEmbed", "path": "content", "model": "voyage-4-lite", "modality": "text" }, { "type": "filter", "path": "scope" }, { "type": "filter", "path": "store_name" } ]}Nota
Por defecto, este índice de búsqueda vectorial de MongoDB utiliza el tipo autoEmbed , que indica a MongoDB que genere las incrustaciones automáticamente.
El índice de búsqueda de MongoDB se nombra según la clave de text_index_name del diccionario MongoDBConfig y tiene la siguiente definición:
{ "mappings": { "dynamic": false, "fields": { "content": [{ "type": "string" }] } }}Para obtener más información sobre cómo crear estos índices manualmente, consulte Crear un índice de búsqueda vectorial de MongoDB y un índice de búsqueda de MongoDB.
Incrustación manual
Para proporcionar tus propias incrustaciones vectoriales, configura las claves embedding_dimensions y similarity del diccionario MongoDBConfig. No configures la clave embedding_model. Con esta configuración, MongoDB indexa un campo embedding como tipo vector, en lugar de un campo content como tipo autoEmbed.
Luego, proporciona los vectores de una de las siguientes maneras:
Pasa un objeto
embedderal constructorMongoDBMemoryStore, que indica al almacén que incruste memorias y consultas en cadenaAl llamar al método
search(), pasa un vector precalculado en la teclavectorde un diccionarioMongoDBSearchQuery
Permisos
La siguiente tabla describe los privilegios que su usuario de base de datos requiere para diferentes acciones:
Privilegio | Necesario Para | Obligatorio cuando |
|---|---|---|
Cada lectura, en ambas clases | Siempre | |
| Siempre, para una instancia de almacenamiento o almacenamiento escribible | |
Comprueba la ordenación para que cada llamada de | Siempre | |
Verificación de índices | Siempre | |
Creación de índices | Solo cuando |
Para conceder estos privilegios, crea un rol personalizado con rango de tus colecciones de almacenamiento y memoria.
Nota
Por defecto, los métodos initialize() y ensure_indexes() crean los índices que el paquete requiere si no existen ya. Las aplicaciones de producción suelen ejecutarse como usuario sin los privilegios createIndex, createCollectiony createSearchIndexes, o dejan la creación de índices a un paso de despliegue separado. En ese caso, configure la clave de ensure_indexes del diccionario MongoDBConfig a False. Esto indica al paquete que verifique los índices en lugar de crearlos.
Recursos adicionales
Para obtener más información sobre el uso de Agentes de Hilos con MongoDB, consulte los siguientes recursos:
strands-mongodb Repositorio de GitHub
strands-mongodb en PyPI