Integrar MongoDB con Google ADK

Configurar los ajustes

MongoDbToolSettings es una clase de configuración que configura el modelo de incrustación, los nombres de los índices y los límites de búsqueda que utiliza MongoDbToolset. Pase una instancia de esta clase al parámetro settings de MongoDbToolset para anular sus valores predeterminados, como se muestra en el siguiente ejemplo:

from google.adk.integrations.mongodb import MongoDbToolsetfrom google.adk.integrations.mongodb import MongoDbToolSettings
toolset = MongoDbToolset(    connection_string="<connection_string>",    database_name="products_db",    settings=MongoDbToolSettings(default_limit=8, max_results=20),)

Modos de incrustación

Antes de ejecutar una búsqueda vectorial, el conjunto de herramientas inserta el texto de su consulta. Seleccione la pestaña Atlas Automated Embedding para permitir que Atlas inserte las consultas automáticamente, o seleccione la pestaña Google embedding models para ver el comportamiento de inserción predeterminado:

from google.adk.integrations.mongodb import MongoDbToolsetfrom google.adk.integrations.mongodb import MongoDbToolSettings
toolset = MongoDbToolset(    connection_string="<connection_string>",    database_name="products_db",    settings=MongoDbToolSettings(        use_mongodb_auto_embedding=True,        mongodb_auto_embedding_model="voyage-4",  # optional    ),)

from google.adk.integrations.mongodb import MongoDbToolset
toolset = MongoDbToolset(    connection_string="<connection_string>",    database_name="products_db",)

Selección de colección

El modelo selecciona la colección en cada llamada, por lo que un conjunto de herramientas vinculado a una base de datos accede a todas las colecciones de esa base de datos que tengan un índice de búsqueda. Configure el parámetro database_name con una base de datos que contenga solo los datos que el agente tiene permiso para leer y almacene cualquier otro dato en una base de datos separada.

El parámetro tool_filter no restringe las colecciones a las que el modelo puede acceder, ya que selecciona herramientas completas y no recibe argumentos de llamada. Para imponer una lista de colecciones permitidas, utilice el hook before_tool_callback, que sí recibe los argumentos de llamada:

from google.adk.agents import Agentfrom google.adk.integrations.mongodb import MongoDbToolset

def allow_products_only(tool, args, tool_context):  if tool.name.startswith("mongodb_") and args.get("collection_name") != "products":    return {        "status": "ERROR",        "error_details": "Only the products collection may be searched.",    }  return None

agent = Agent(    name="product_search_agent",    instruction="Answer questions about products.",    tools=[        MongoDbToolset(            connection_string="<connection_string>",            database_name="products_db",        )    ],    before_tool_callback=allow_products_only,)

Si la función de devolución de llamada devuelve un diccionario, ADK nunca ejecuta la herramienta de búsqueda. En su lugar, envía ese diccionario al agente como si fuera la propia salida de la herramienta. Devolver None permite que la herramienta de búsqueda se ejecute con normalidad.

Diseño del documento

MongoDbSessionService Almacena datos en las siguientes colecciones:

Google ADK limita el estado a la aplicación, un usuario o la sesión actual con un prefijo app: o user: en la clave de estado. MongoDbSessionService almacena cada valor en la colección correspondiente y elimina el prefijo de la clave almacenada, por lo que un valor establecido con la clave app:theme se almacena en la colección app_states como theme.

Modelo de concurrencia

El modelo de concurrencia del servicio depende de su tipo de implementación:

• En un conjunto de réplicas, un clúster fragmentado o un clúster Atlas, cada escritura de varios documentos se ejecuta en una transacción, por lo que se confirma o se cancela de forma atómica.

• En una instancia mongod independiente, o en cualquier implementación sin soporte para transacciones, el servicio recurre a escrituras secuenciales con una comprobación de revisión de concurrencia optimista en el documento de sesión.

Dentro de un mismo proceso, un bloqueo por sesión impide que se escriba en la misma sesión simultáneamente. Este bloqueo no tiene efecto en múltiples procesos, por ejemplo, cuando varias instancias de la aplicación escriben en la misma sesión al mismo tiempo.

En múltiples procesos, la comprobación de revisión del documento de sesión evita la corrupción de datos. Si dos escrituras compiten, la que se completa primero incrementa el número de revisión, y la otra no supera la comprobación. Su aplicación debe detectar este fallo, recargar la sesión para obtener su estado actual y volver a intentar la escritura.

Considerations

Al utilizar el servicio de memoria, tenga en cuenta el siguiente comportamiento:

• Al realizar una búsqueda en la memoria, el servicio devuelve documentos cuya matriz de palabras clave coincide con las palabras clave de la consulta.

• La ingesta es idempotente. Si vuelves a ingerir una sesión, el servicio sobrescribe sus recuerdos en lugar de duplicarlos.

• La recuperación realiza una búsqueda por palabra clave y no requiere un modelo de incrustación, credenciales de Google ni un índice vectorial. Por lo tanto, la recuperación de memoria funciona en cualquier implementación de MongoDB.