Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

Integra MongoDB con Agentes de Hilo

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.

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.

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]' # MongoDBMemoryStore

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.

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 .

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.

La siguiente tabla enumera los métodos proporcionados por la clase MongoDBStorage :

Método
Descripción
Parámetros
Valor de retorno

write()

Almacena datos persistentes como bytes en una clave, reemplazando cualquier valor existente. Si configuras ttl_seconds, este método también añade un campo expires_at al documento que escribe.

key: La clave para almacenar los datos debajo.
data: Los bytes a almacenar.

None

read()

Devuelve los bytes almacenados en una clave.

key: La clave a leer.

bytes, o None cuando la clave está ausente

delete()

Elimina una clave. Si eliminas una clave que no existe, este método no genera ningún error.

key: La clave a eliminar.

None

list()

Devuelve los nombres de las claves que comienzan con un prefijo, en orden ascendente. Devuelve solo las claves, no los valores almacenados.

query: El prefijo de tecla que debe coincidir.

list[str]

search()

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 search_strategy MongoDBStoragea una estrategia que lea valores, como el KeywordSearchStrategy del SDK o MongoDBVectorSearchStrategy para la búsqueda vectorial.

query: El texto a buscar.

list[StorageSearchResult]

delete_prefix()

Elimina todas las teclas que comienzan con un prefijo especificado.

prefix: El prefijo de tecla a eliminar.

int, que indica el número de documentos eliminados

namespace()

Devuelve un nuevo MongoDBStorage asignado a un prefijo en la misma colección, compartiendo el grupo de conexiones original, la colección, el TTL y la estrategia de búsqueda. Este método es síncrono.

prefix: El prefijo que delimita el ámbito de la nueva instancia.

MongoDBStorage

ensure_indexes()

Crea o verifica el índice TTL que ttl_seconds requiere. Llama a este método una vez al iniciar.

Ninguno

None

close()

Libera el grupo de conexiones para cada instancia que comparte el mismo diccionario MongoDBConfig . Llama a este método una vez en el cierre del proceso.

Ninguno

None

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.

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 .

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 de scope campo. 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())

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.

La siguiente tabla enumera los métodos proporcionados por la clase MongoDBMemoryStore :

Método
Descripción
Parámetros
Valor de retorno

add()

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.

content: El texto de la memoria.
metadata: Pares clave-valor opcionales para almacenar con la memoria.

MongoDBAddResult, que contiene ids, inserted, y duplicates

search()

Devuelve las memorias que mejor coinciden con una consulta en orden de relevancia. Acepta una cadena simple o un diccionario MongoDBSearchQuery para un filtro, límite o vector por consulta.

query: El texto a buscar, o un diccionario MongoDBSearchQuery .
options: Opciones opcionales de búsqueda del SDK, como max_search_results.

list[MemoryEntry]. Los metadatos de cada entrada incluyen _relevance_score, _search_type, _scope, y _id.

initialize()

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 MemoryManager y por cada método que lee o escribe memorias.

Ninguno

None

delete()

Elimina una memoria, identificada por la _id que informa un resultado de búsqueda. Para utilizar este método, debes establecer writable como True.

memory_id: El valor _id de un resultado de búsqueda.

int, que es 1 si un documento fue eliminado o 0 si ninguno coincide

delete_all()

Elimina toda memoria que este almacén pueda leer. Para utilizar este método, debes establecer writable como True.

Ninguno

intindica la cantidad de documentos eliminados

close()

Libera el grupo de conexiones para cada instancia que comparte el mismo diccionario MongoDBConfig .

Ninguno

None

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.

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 writable en True.

  • La clase MemoryManager siempre proporciona al modelo una herramienta search_memory , pero solo proporciona una herramienta add_memory cuando add_tool_config está configurada en True. Si quieres que el modelo decida cuándo guardar una memoria, activa el parámetro add_tool_config .

  • El parámetro add_tool_config genera un ValueError si ninguna tienda que pases es escribible.

  • El parámetro storage por sí solo no mantiene las sesiones persistentes. Debes configurar session_manager para guardar las sesiones bajo el valor de session_id especificado.

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.

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 embedder al constructor MongoDBMemoryStore , que indica al almacén que incruste memorias y consultas en cadena

  • Al llamar al método search(), pasa un vector precalculado en la tecla vector de un diccionario MongoDBSearchQuery

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

write(), add(), delete(), y métodos similares

Siempre, para una instancia de almacenamiento o almacenamiento escribible

Comprueba la ordenación para que cada llamada de initialize() se ejecute antes que cualquier índice

Siempre

Verificación de índices

Siempre

Creación de índices

Solo cuando ensure_indexes está configurado en True, su valor predeterminado

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.

Para obtener más información sobre el uso de Agentes de Hilos con MongoDB, consulte los siguientes recursos: