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:
Configura tu entorno.
Cree una colección y un índice de búsqueda vectorial.
Crea un agente que busque en tu colección.
Añade sesiones persistentes para que el agente recuerde los turnos anteriores.
Ejecute el archivo y haga una revisión de la salida.
Segundo plano
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.
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.
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.
Configurar el entorno
En esta sección, preparará su entorno instalando las dependencias necesarias, configurando las variables de entorno y creando un archivo de proyecto.
Establecer las variables de entorno.
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.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 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.
Crea tu colección e índice.
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.
Insertar documentos de ejemplo.
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.", }, ])Cree el índice de incrustación automatizada de Atlas.
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.
Configurar herramientas y sesiones de agente
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.
Configurar el conjunto de herramientas.
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.
Defina el agente.
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],)Configure el servicio de sesión y un ejecutor.
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.
Haz que el agente participe en dos turnos de conversación.
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.
Ejecutar el archivo
Para ejecutar el archivo main.py, ejecute el siguiente comando desde su directorio google-adk-mongodb-project:
python main.pySi 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.Próximos pasos
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.