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.

Comience a utilizar la integración de MongoDB con Google ADK.

Puedes integrar MongoDB con Google ADK para configurar las herramientas de búsqueda del agente y el historial de conversaciones persistente, ambos respaldados por MongoDB. Este tutorial utiliza la clase MongoDbToolset para permitir que un agente de Google ADK busque en una colección que contiene datos de pingüinos. Luego, el tutorial utiliza la clase MongoDbSessionService, que permite al agente acceder a turnos anteriores en la conversación.

En este tutorial, realizarás las siguientes tareas:

  1. Configura tu entorno.

  2. Cree una colección y un índice de búsqueda vectorial.

  3. Crea un agente que busque en tu colección.

  4. Añade sesiones persistentes para que el agente recuerde los turnos anteriores.

  5. Ejecute el archivo y haga una revisión de la salida.

Google ADK es un framework de Python de código abierto para la creación de agentes de IA. Este tutorial utiliza los siguientes componentes de Google ADK para configurar un agente y habilitar el acceso a MongoDB:

  • MongoDbToolsetProporciona búsqueda vectorial de MongoDB y herramientas de búsqueda híbrida en una base de datos MongoDB.

  • MongoDbSessionService: Persiste las sesiones, eventos y estado del agente en MongoDB

Este tutorial configura la clase MongoDbToolset para usar Atlas Automated Embedding, que incrusta tanto los documentos almacenados como las consultas de búsqueda sin necesidad de un modelo de incrustación independiente ni credenciales de Google.

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.

  • Clave API de Gemini. Este tutorial utiliza un modelo de Gemini, pero puedes usar cualquier proveedor compatible. Para obtener más información, consulta la sección Modelos en la documentación de Google ADK.

  • Python v3.11 o posterior.

En esta sección, preparará su entorno instalando las dependencias necesarias, configurando las variables de entorno y creando un archivo de proyecto.

1

Ejecuta los siguientes comandos en tu terminal para crear un nuevo directorio llamado google-adk-mongodb-project e instalar las dependencias necesarias:

mkdir google-adk-mongodb-projectcd google-adk-mongodb-projectpip install "google-adk[mongodb]" python-dotenv
2

En tu directorio google-adk-mongodb-project, crea un archivo .env y añade el siguiente código:

GOOGLE_API_KEY="<gemini-api-key>"MONGODB_URI="<connection-string>"

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.net

IMPORTANTE: 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.

3

En tu directorio google-adk-mongodb-project, crea un archivo llamado main.py. Agrega el siguiente código a este archivo para cargar tus variables de entorno e importar los módulos necesarios:

import osimport timeimport asynciofrom dotenv import load_dotenvfrom pymongo import MongoClientfrom pymongo.operations import SearchIndexModelfrom google.adk.agents import Agentfrom google.adk.integrations.mongodb import ( MongoDbToolset, MongoDbToolSettings, MongoDbSessionService,)from google.adk.runners import Runnerfrom google.genai import types load_dotenv()

En los siguientes pasos, deberá agregar código a este archivo para crear su colección, compilar su agente y ejecutarlo.

En esta sección, insertará documentos de ejemplo sobre pingüinos en una colección de MongoDB y creará el índice de búsqueda vectorial de MongoDB que requiere Atlas Automated Embedding.

1

Agregue el siguiente código a su archivo main.py para crear una colección penguins en la base de datos google_adk_tutorial, o acceda a ella si la colección ya existe:

client = MongoClient(os.environ["MONGODB_URI"])collection = client["google_adk_tutorial"]["penguins"]
2

Agregue el siguiente código a su archivo main.py para insertar cinco documentos que describen pingüinos en su colección. El campo embeddings almacena el texto que Atlas inserta automáticamente:

collection.insert_many( [ { "title": "Emperor Penguins", "embeddings": "Emperor penguins are the tallest and heaviest of all penguin species, standing up to 4 feet.", }, { "title": "Penguin Habitats", "embeddings": "Penguins are flightless seabirds that live almost exclusively below the equator. Some island-dwellers can be found in warmer climates.", }, { "title": "Penguins of Patagonia", "embeddings": "Patagonia is home to five penguin species: Magellanic, Humboldt, Gentoo, Southern Rockhopper, and King.", }, { "title": "Penguin Diving Depths", "embeddings": "Emperor penguins can dive deeper than any other bird, reaching depths of over 500 meters.", }, { "title": "Penguin Nesting Habits", "embeddings": "Some penguin species mate for life and return to the same nesting site every year.", }, ])
3

Agregue el siguiente código a su archivo main.py para crear un índice de búsqueda vectorial de MongoDB en el campo embeddings. El tipo de campo autoEmbed indica a Atlas que genere y almacene automáticamente las incrustaciones para este campo:

search_index_model = SearchIndexModel( definition={ "fields": [ { "type": "autoEmbed", "path": "embeddings", "model": "voyage-4", "modality": "text", } ] }, name="autoembed_index", type="vectorSearch",) collection.create_search_index(model=search_index_model) # Index build time varies with collection size and cluster typeprint("Waiting for the MongoDB Vector Search index to finish building...")time.sleep(60) client.close()

El índice debería tardar alrededor de un minuto en compilarse. Mientras se crea, el índice se encuentra en un estado de sincronización inicial. Cuando se termine de construir, se podrá empezar a consultar los datos de tu colección.

En esta sección, crearás un agente que utiliza la clase MongoDbToolset para buscar en tu colección. Luego, configurarás la clase MongoDbSessionService para guardar el historial de conversaciones del agente en MongoDB.

1

Agregue el siguiente código a su archivo main.py para vincular MongoDbToolset a su base de datos y configurarlo para usar Atlas Automated Embedding:

toolset = MongoDbToolset( connection_string=os.environ["MONGODB_URI"], database_name="google_adk_tutorial", settings=MongoDbToolSettings( use_mongodb_auto_embedding=True, default_embedding_field="embeddings", default_vector_index_name="autoembed_index", ),)

Debido a que la opción use_mongodb_auto_embedding está configurada como True, el conjunto de herramientas envía el texto de la consulta a Atlas como texto plano en lugar de llamar a un modelo de incrustación de Google.

2

Agregue el siguiente código a su archivo main.py para crear un agente que utilice un modelo Gemini y su conjunto de herramientas:

root_agent = Agent( model="gemini-2.5-flash", name="penguin_facts_agent", description="Answers questions about penguins.", instruction=( "Search the penguins collection with your MongoDB" " tools to answer questions about penguins. Remember" " what the user has told you earlier in the" " conversation." ), tools=[toolset],)
3

Agregue el siguiente código a su archivo main.py para configurar la clase MongoDbSessionService y pasarla, junto con su agente, a un objeto Runner:

session_service = MongoDbSessionService( connection_string=os.environ["MONGODB_URI"], database_name="google_adk_tutorial",) runner = Runner( agent=root_agent, app_name="google_adk_tutorial", session_service=session_service,)

Por defecto, MongoDbSessionService crea los índices recomendados para su uso, a menos que configure el parámetro ensure_indexes en False. Para obtener más información, consulte las Directrices de indexación en la documentación de referencia de Google ADK.

4

Agregue el siguiente código a su archivo main.py para crear una sesión y luego envíe dos mensajes al agente a través de esa sesión:

async def ask(runner, session_id, text): content = types.Content(role="user", parts=[types.Part(text=text)]) async for event in runner.run_async( user_id="tutorial_user", session_id=session_id, new_message=content, ): if event.is_final_response() and event.content: print(f"\n[user]: {text}") print(f"[agent]: {event.content.parts[0].text}") async def main(): session = await session_service.create_session( app_name="google_adk_tutorial", user_id="tutorial_user", ) await ask( runner, session.id, "How deep can emperor penguins dive?" ) await ask( runner, session.id, "What was the first thing I asked you?" ) asyncio.run(main())

Dado que ambas llamadas utilizan el mismo valor session_id, MongoDbSessionService carga los eventos del primer turno antes de que el agente responda al segundo mensaje. Si se crea una nueva sesión para la segunda llamada, el agente no tendrá registro del primer turno.

Para ejecutar el archivo main.py, ejecute el siguiente comando desde su directorio google-adk-mongodb-project:

python main.py

Si el comando se ejecuta correctamente, el resultado se parecerá al siguiente:

Waiting for the MongoDB Vector Search index to finish building... [user]: How deep can emperor penguins dive?[agent]: Emperor penguins can dive deeper than any other bird,reaching depths of over 500 meters. [user]: What was the first thing I asked you?[agent]: The first thing you asked me was about how deep emperorpenguins can dive.

Para obtener más información sobre MongoDbToolset, MongoDbSessionService y MongoDbMemoryService, incluyendo su referencia completa de parámetros y métodos, consulte Integrar MongoDB con Google ADK.

Para obtener más información sobre Google ADK, consulte el repositorio de GitHub adk-python.