Integre MongoDB con el marco Agno

Puede integrar MongoDB con Agno, un marco de Python de código abierto para crear agentes de IA multimodales. Agno ofrece dos integraciones de MongoDB:

Base de datos vectorial que almacena la Base de Conocimiento de su agente y la recupera con MongoDB búsqueda vectorial.
Base de datos de sesión y memoria que persiste sesiones de agente, memorias de usuario, métricas y ejecuciones de evaluación en sus colecciones de MongoDB.

Puedes usar cualquiera de las integraciones por sí sola, o puedes usar ambas en el mismo agente.

Empezar

Para completar un tutorial que configure Agno para utilizar MongoDB, consulte Primeros pasos con la integración de MongoDB Agno.

Instalación

Agno requiere Python v3.9 o posterior. Para instalar las últimas versiones de Agno y PyMongo, ejecuta el siguiente comando:

pip install agno pymongo

Los ejemplos de esta página utilizan modelos de OpenAI, que Agno utiliza por defecto. Para instalar la librería de cliente de OpenAI, ejecute el siguiente comando:

pip install openai

Los Custom configuration ejemplos de esta página utilizan incrustaciones de Voyage AI. Para instalar la librería de cliente de Voyage AI, ejecute el siguiente comando:

pip install voyageai

Variables de entorno

Antes de ejecutar los ejemplos en esta página, configure las siguientes variables de entorno:

Cadena de conexión: Establezca MONGODB_URI en la cadena de conexión para su implementación de MongoDB.
Clave de API del modelo: Establezca OPENAI_API_KEY o VOYAGE_API_KEY en la clave de API de su proveedor de modelos.

base de datos vectorial

La clase MongoVectorDb implementa la interfaz de base de datos vectorial Agno con la búsqueda vectorial de MongoDB. Para que un agente realice una búsqueda semántica en sus documentos, pase una instancia de esta clase al parámetro vector_db de un objeto Agno Knowledge, y luego pase ese objeto al parámetro knowledge de su agente.

Importante

Nombres de clase de MongoDB

Agno nombra ambas clases de MongoDB MongoDb, pero las importa de módulos diferentes. Importe la clase de base de datos vectorial de agno.vectordb.mongodb y la clase de base de datos de agno.db.mongo. Para evitar una colisión de nombres, Agno también exporta la clase de base de datos vectorial como MongoVectorDb. Los ejemplos en esta página utilizan ese alias.

Seleccione la pestaña Basic initialization para ver un ejemplo de configuración mínima, o seleccione la pestaña Custom configuration para ver cómo configurar la integración con ajustes personalizados.

Para inicializar la base de datos vectorial, especifique la colección que almacena sus incrustaciones y su cadena de conexión de MongoDB. El siguiente ejemplo crea una Base de Conocimiento, añade un documento y le da a un agente acceso a los datos:

import osfrom agno.agent import Agentfrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.mongodb import MongoVectorDb
vector_db = MongoVectorDb(    collection_name="agent_knowledge",    db_url=os.environ["MONGODB_URI"],    database="agno",)
knowledge = Knowledge(vector_db=vector_db)knowledge.insert(    name="Recipes",    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",)
agent = Agent(knowledge=knowledge, search_knowledge=True)

El siguiente ejemplo habilita la búsqueda híbrida, utiliza Voyage AI para generar incrustaciones en lugar del valor por defecto de OpenAI, y especifica un nombre de índice de búsqueda vectorial de MongoDB:

import osfrom agno.agent import Agentfrom agno.knowledge.embedder.voyageai import VoyageAIEmbedderfrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.mongodb import MongoVectorDbfrom agno.vectordb.search import SearchType
embedder = VoyageAIEmbedder(    id="voyage-4-large",    dimensions=1024,    api_key=os.environ["VOYAGE_API_KEY"],    request_params={"output_dimension": 1024},)
vector_db = MongoVectorDb(    collection_name="agent_knowledge",    db_url=os.environ["MONGODB_URI"],    database="agno",    embedder=embedder,    search_type=SearchType.hybrid,    hybrid_vector_weight=0.7,    hybrid_keyword_weight=0.3,    search_index_name="agno_vector_index",)
knowledge = Knowledge(vector_db=vector_db)agent = Agent(knowledge=knowledge, search_knowledge=True)

Si especifica un incrustador, Agno utiliza el número de dimensiones que produce el incrustador cuando crea el índice de búsqueda vectorial de MongoDB. El diccionario request_params pasa argumentos de palabra clave específicos del proveedor a la llamar de incrustación. Para Voyage AI, output_dimension controla el tamaño del vector devuelto para los modelos que admiten dimensiones variables.

Cuando crea un objeto Knowledge, Agno verifica si la colección ya existe. Si no lo hace, Agno crea la colección y el índice de búsqueda vectorial de MongoDB. Si la colección existe, Agno no comprueba si el índice existe, incluso si usted lo borró por separado.

Después de crear el índice, Agno espera hasta que el índice aparezca en la colección. Sin embargo, no verifica el estado del índice, por lo que una query que se ejecuta inmediatamente después puede devolver ningún resultado mientras el índice termina de crearse.

La clase MongoVectorDb acepta los siguientes parámetros:

Parameter	Necesidad	Descripción
`collection_name`	Requerido	El nombre de la colección que almacena sus documentos e incrustaciones.
`db_url`	Opcional	La cadena de conexión para la implementación de MongoDB. Se establece en `mongodb://localhost:27017/` por defecto. Para obtener más información sobre cómo encontrar su cadena de conexión, consulte Conéctese a un clúster a través de las librerías de cliente.
`client`	Opcional	Una instancia existente de `MongoClient`. Si especifica este parámetro, Agno ignora `db_url`.
`database`	Opcional	El nombre de la base de datos que contiene la colección. Se establece por defecto en `agno`.
`embedder`	Opcional	El modelo de incrustación que Agno utiliza para incrustar sus documentos y queries. Se establece por defecto en `OpenAIEmbedder()`.
`distance_metric`	Opcional	La función de similitud que utiliza el índice de búsqueda vectorial de MongoDB. Actualmente solo se admite el valor por defecto, `Distance.cosine`.
`search_type`	Opcional	La estrategia de recuperación. Acepta `SearchType.vector` o `SearchType.hybrid`. Se establece por defecto en `SearchType.vector`.
`hybrid_vector_weight`	Opcional	El peso que la búsqueda híbrida aplica a los resultados semánticos. Se establece por defecto en `0.5`.
`hybrid_keyword_weight`	Opcional	El peso que la búsqueda híbrida aplica a los resultados de palabras clave. Se establece por defecto en `0.5`.
`hybrid_rank_constant`	Opcional	La constante que la búsqueda híbrida añade a cada rango antes de calcular la puntuación de fusión de rango recíproco. Se establece por defecto en `60`.
`search_index_name`	Opcional	El nombre del índice de MongoDB búsqueda vectorial en su colección. Se establece por defecto en `vector_index_1`.
`wait_until_index_ready_in_seconds`	Opcional	Si Agno espera, después de crear el índice de búsqueda vectorial de MongoDB, a que aparezca el nombre del índice en los índices de búsqueda de la colección. Establezca este parámetro en un número positivo para esperar, o en `None` para omitir la espera. Los métodos asíncronos utilizan el valor como tiempo de espera, en segundos. Por defecto es `3`.
`wait_after_insert_in_seconds`	Opcional	El tiempo, en segundos, que Agno espera después de insertar documentos. Se establece por defecto en `3`.
`max_pool_size`	Opcional	La cantidad máxima de conexiones en el pool de conexiones del driver. Se establece por defecto en `100`.
`retry_writes`	Opcional	Si el driver reintenta las operaciones de guardar admitidas. Se establece por defecto en `True`.
`cosmos_compatibility`	Opcional	Si Agno crea índices en el formato de Azure Cosmos DB para MongoDB vCore en lugar del formato de búsqueda vectorial de MongoDB. Se establece por defecto en `False`.
`name`, `description`, `id`	Opcional	Los metadatos identificativos para la instancia de la base de datos vectorial. Si no especifica `id`, Agno lo deriva de la cadena de conexión, el nombre de la base de datos y el nombre de la colección.

Métodos de base de datos vectorial

La clase Knowledge llama a los siguientes métodos cuando se añade contenido a una Base de Conocimiento o cuando un agente la busca. llamar a estos métodos directamente solo si gestiona documentos fuera de un objeto Knowledge.

Para limitar una operación de guardar o búsqueda a los documentos de un solo usuario, pase un valor user_id al método de operación.

Método	Descripción
`search(query, limit, filters, min_score, user_id)`	Integra `query` y devuelve hasta `limit` documentos coincidentes. Si establece `search_type` en `SearchType.hybrid`, Agno también ejecuta una búsqueda por palabras clave y combina los dos conjuntos de resultados. El parámetro `filters` acepta un diccionario de filtros de metadatos. Si pasa una lista de expresiones de filtro de Agno en su lugar, Agno deja un registro de una advertencia y no aplica ningún filtro porque la integración de MongoDB no los admite.
`insert(content_hash, documents, filters, user_id)`	Incrusta cada documento en `documents` e inserta los documentos en su colección. Agno deriva el valor `_id` de cada documento de un código hash del contenido del documento.
`upsert(content_hash, documents, filters, user_id)`	Reemplaza los documentos que comparten `content_hash`, luego inserta los documentos en `documents`. Utilice este método para actualizar un documento cuyo contenido ha cambiado.
`delete()`	Borra todos los documentos de su colección, pero mantiene la colección y su índice de búsqueda vectorial de MongoDB.
`delete_by_id(id)`	Borrar el documento con el valor `_id` especificado.
`delete_by_name(name)`	Elimina los documentos con el valor `name` especificado.
`delete_by_metadata(metadata)`	Borrar los documentos cuyo campo `meta_data` coincide con los pares clave-valor especificados.
`drop()`	Descartar su colección y su índice de búsqueda vectorial de MongoDB.
`exists()`	Devuelve `True` si su colección existe.
`get_count()`	Devuelve el número de documentos de su colección.

Tip

Métodos asíncronos

Cada uno de los siguientes métodos descritos en la tabla anterior tiene un método asíncrono correspondiente:

search(): Usar async_search()
insert(): Usar async_insert()
upsert(): Usar async_upsert()
drop(): Usar async_drop()
exists(): Usar async_exists()

Base de datos de sesión y memoria

La clase MongoDb en el módulo agno.db.mongo implementa la interfaz de base de datos de Agno. Para conservar las sesiones de un agente, las memorias de usuario, las métricas y las ejecuciones de evaluación en MongoDB, pase una instancia de esta clase al parámetro db de un objeto Agent, Team o Workflow.

Para inicializar la base de datos, especifique su cadena de conexión de MongoDB. El siguiente ejemplo crea un agente que almacena su historial de sesión en MongoDB e incluye ese historial en el contexto del modelo:

import osfrom agno.agent import Agentfrom agno.db.mongo import MongoDb
db = MongoDb(db_url=os.environ["MONGODB_URI"])
agent = Agent(db=db, add_history_to_context=True)

El siguiente ejemplo especifica el nombre de la base de datos y los nombres de las colecciones que almacenan sesiones, recuerdos y métricas:

import osfrom agno.agent import Agentfrom agno.db.mongo import MongoDb
db = MongoDb(    db_url=os.environ["MONGODB_URI"],    db_name="agno_prod",    session_collection="agent_sessions",    memory_collection="agent_memories",    metrics_collection="agent_metrics",)
agent = Agent(db=db, add_history_to_context=True)

Agno crea cada colección que configura la primera vez que escribe en esa colección.

La clase MongoDb acepta los siguientes parámetros:

Parameter	Necesidad	Descripción
`db_url`	Condicional	La cadena de conexión para la implementación de MongoDB. Obligatorio si no especifica `db_client`.
`db_client`	Condicional	Una instancia existente de `MongoClient`. Obligatorio si no especifica `db_url`. Si especifica ambos, Agno ignora `db_url`.
`db_name`	Opcional	El nombre de la base de datos que contiene las colecciones. Se establece por defecto en `agno`.
`session_collection`	Opcional	El nombre de la colección que almacena sesiones de agente, equipo y flujo de trabajo. Se establece por defecto en `agno_sessions`.
`runs_collection`	Opcional	El nombre de la colección que almacena ejecuciones, con un documento por ejecución. Se establece por defecto en `agno_runs`. Si especifica `session_collection` pero no este parámetro, Agno crea el nombre a partir del nombre de su colección de sesión, como `agent_sessions_runs`.
`memory_collection`	Opcional	El nombre de la colección que almacena recuerdos de usuario. Se establece por defecto en `agno_memories`.
`metrics_collection`	Opcional	El nombre de la colección que almacena métricas de uso agregadas. Se establece por defecto en `agno_metrics`.
`eval_collection`	Opcional	El nombre de la colección que almacena las ejecutar de evaluación. Se establece por defecto en `agno_eval_runs`.
`knowledge_collection`	Opcional	El nombre de la colección que almacena metadatos de contenido de conocimiento. Se establece por defecto en `agno_knowledge`.
`traces_collection`, `spans_collection`	Opcional	Los nombres de las colecciones que almacenan rastros y tramos. Por defecto, es `agno_traces` y `agno_spans`.
`schedules_collection`, `schedule_runs_collection`	Opcional	Los nombres de las colecciones que almacenan cronogramas y ejecutar de cronogramas. Por defecto, es `agno_schedules` y `agno_schedule_runs`.
`learnings_collection`	Opcional	El nombre de la colección que almacena aprendizajes. Se establece por defecto en `agno_learnings`.
`id`	Opcional	El identificador de la instancia de base de datos. Si no especifica este parámetro, Agno lo deriva de la cadena de conexión y el nombre de la base de datos.

Mientras se ejecuta el agente, Agno lee y escribe automáticamente en las colecciones de sesión, memoria y métricas descritas en esta sección. Agno crea cada colección la primera vez que se necesita. También puede llamar a métodos directamente en su instancia de MongoDb, como los siguientes:

upsert_session() y get_sessions() sesiones de lectura y guardar.
upsert_user_memory() guardar una única memoria de usuario.
get_metrics() lee métricas de uso agregadas.
upsert_sessions() y upsert_memories() guarda muchos registros en una sola operación, como cuando migra el historial de sesiones existente a MongoDB.
close() libera la conexión del cliente. Llame a este método cuando su aplicación se apague.

índice de búsqueda

La primera vez que Agno crea su colección vectorial, también crea un índice de búsqueda vectorial de MongoDB en la colección. El nombre del índice es el valor del parámetro search_index_name, que por defecto es vector_index_1. También puede crear o inspeccionar este índice manualmente. Para obtener más información, consulta Crea un índice de MongoDB búsqueda vectorial.

El índice utiliza la siguiente definición, donde numDimensions coincide con el número de dimensiones que produce su incrustador y similarity coincide con su valor distance_metric:

{  "fields": [    {      "type": "vector",      "path": "embedding",      "numDimensions": 1536,      "similarity": "cosine"    },    {      "type": "filter",      "path": "user_id"    }  ]}

Agno indexa el campo user_id como un campo de filtro para que pueda limitar las búsquedas a los documentos de un único usuario final.

La búsqueda híbrida no requiere un índice de búsqueda de MongoDB Search. Agno ejecuta su búsqueda de palabras clave como una query de expresión regular en el campo content, luego combina esos resultados con los resultados de la búsqueda vectorial de MongoDB mediante el uso de la fusión de rango recíproco.