对于 AI 代理：可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

将MongoDB与 Google ADK 集成

您可以将MongoDB与 Google ADK 集成，后者是一个用于构建AI助手的开源Python框架。该集成提供三个组件：

  • MongoDbToolset，为代理提供MongoDB Vector Search 和混合搜索工具

  • MongoDbSessionService，用于在MongoDB中保存代理会话、事件和状态

  • MongoDbMemoryService，它将会话事件存储在MongoDB中，以实现基于关键字的长期记忆调用

开始体验

要完成将 Google ADK 配置为使用MongoDB 的教程，请参阅开始使用MongoDB Google ADK 集成。

安装

要安装 Google ADK 和MongoDB依赖项，运行以下命令：

pip install "google-adk[mongodb]"

此命令还会安装PyMongo驾驶员。集成需要PyMongo v4.9 或更高版本。

使用

本部分介绍可用于将MongoDB与 Google ADK 集成的三个组件。

MongoDbToolset

MongoDbToolset 是一个工具集类，其中包括以下只读搜索工具，这些工具可以访问权限MongoDB 数据库：

  • mongodb_vector_search：通过嵌入相似度对文档进行排名

  • mongodb_hybrid_search：将该相似度排名与全文排名相结合

重要

所需索引

要使用前面的搜索工具，您必须创建索引指南部分中描述的索引。

调用其中一个工具时，代理模型会将纯文本查询作为工具参数传递。这两个工具都会在内部嵌入此文本，因此模型从不生成或处理向量。

要查看将工具集绑定到MongoDB 数据库的示例，请选择与首选连接方法对应的标签页：

以下示例展示了如何使用连接字符串来配置工具集：

from google.adk.agents import Agentfrom google.adk.integrations.mongodb import MongoDbToolset
toolset = MongoDbToolset(    connection_string="<connection_string>",    database_name="products_db",)
agent = Agent(    model="gemini-2.5-flash",    name="product_search_agent",    instruction=(        "Search the products collection with your MongoDB tools."    ),    tools=[toolset],)

要学习；了解有关查找连接字符串的更多信息，请参阅通过客户端库连接到集群。

在代理指令中为目标集合命名，因为该模型会在每次调用时选择一个集合。有关这对工具集可以访问权限的数据的影响，请参阅集合选择部分。

嵌入模型的档案来自应用程序默认档案，这是 Google Cloud 用于发现凭证的标准机制。 MongoDB的档案来自连接字符串。

配置设置

MongoDbToolSettings 是一个设置类，用于配置 MongoDbToolset 使用的嵌入模型、索引名称和搜索限制。将此类的实例传递给 MongoDbToolset 的 settings 参数以覆盖其默认值，如以下示例所示：

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),)

嵌入模式

在运行向量搜索之前，工具集会嵌入查询文本。选择 Atlas Automated Embedding标签页以允许Atlas自动嵌入查询，或者选择 Google embedding models标签页以查看默认嵌入行为：

要使用Atlas自动嵌入，请在 MongoDbToolSettings 配置类上将 use_mongodb_auto_embedding 参数设立为 True。以下示例展示了此配置：

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    ),)

使用此配置，工具集不会进行 Google 嵌入调用。相反，向量搜索阶段会接收查询文本， Atlas使用在索引上配置的 Voyage AI模型生成嵌入。搜索字段必须按 autoEmbed 类型进行索引。

提示

预览功能

Atlas自动嵌入还可作为自托管部署的预览功能使用。要学习；了解详情，请参阅关于 autoEmbed 类型。

集合选择

该模型会在每次调用时选择集合，因此绑定到数据库的工具集会访问该数据库中具有搜索索引的每个集合。将 database_name 参数设置为仅包含允许代理读取的数据的数据库，并将任何其他数据存储在单独的数据库中。

tool_filter 参数不限制模型可以访问权限哪些集合，因为它会选择整个工具并且不接收调用参数。要实施集合允许列表，请改用 before_tool_callback 钩子，该钩子会接收调用参数：

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,)

如果回调返回字典，则 ADK 从不运行搜索工具。相反，它会将该字典发送给代理，就像它是工具自己的输出一样。返回 None 允许搜索工具正常运行。

MongoDbSessionService

MongoDbSessionService 将会话、事件以及应用、用户和会话范围的状态存储在MongoDB中。将其传递给 Runner对象，以便为代理配置持久对话历史记录，如以下示例所示：

from google.adk.integrations.mongodb import MongoDbSessionServicefrom google.adk.runners import Runner
session_service = MongoDbSessionService(    connection_string="<connection_string>",    database_name="my_app",)
runner = Runner(    agent=agent,    app_name="my_app",    session_service=session_service,)

文档布局

MongoDbSessionService 将数据存储在以下集合中：

Collection
_id 值
目录

sessions

<app_name>/<user_id>/<session_id>

JSON格式的会话范围状态、时间戳和乐观并发修订号

events

<app_name>/<user_id>/<session_id>/<event_id>

完整序列化事件

app_states

<app_name>

应用范围的状态

user_states

<app_name>/<user_id>

用户范围的状态

Google ADK 将状态范围限定为应用、用户或当前会话，状态键上带有 app: 或 user: 前缀。 MongoDbSessionService 将每个值存储在相应的集合中，并从存储的键中去掉前缀，因此使用键 app:theme设立的值会作为 theme 存储在 app_states集合中。

注意

每个集合的 state字段将其键和值存储为JSON编码的字符串，而不是存储为原生MongoDB文档。因此，在存储和检索包含MongoDB禁止在文档字段名称中使用的字符（例如 . 或 $）的状态键时，不会导致数据丢失或损坏。

并发模型

服务的并发模型取决于您的部署类型：

  • 在副本集、分片集群或Atlas 集群上，每个多文档写入都在ACID 事务中运行，因此它会自动提交或中止。

  • 在独立运行的mongod 或任何不支持ACID 事务的部署中，该服务会回退到顺序写入，并对会话文档进行开放式并发修订检查。

在单个进程中，每会话锁可防止对同一会话进行并发写入。此锁在多个进程中没有影响，例如当应用程序的多个实例同时写入同一会话时。

在多个进程中，会话文档的修订检查可防止数据损坏。如果两个写入竞争，则先完成的写入会递增修订号，而另一个写入无法通过修订检查。您的应用程序必须捕获此故障，重新加载会话以获取其当前状态，然后重试写入。

MongoDbMemoryService

MongoDbMemoryService 将会话事件存储在内存集合中，并通过关键字匹配来检索这些事件。将其传递给 Runner对象以跨会话配置长期记忆，如以下示例所示：

from google.adk.integrations.mongodb import MongoDbMemoryServicefrom google.adk.runners import Runner
memory_service = MongoDbMemoryService(    connection_string="<connection_string>",    database_name="my_app",)
runner = Runner(    agent=agent,    app_name="my_app",    memory_service=memory_service,)

Runner对象调用内存服务的 add_session_to_memory() 方法，将会话的事件摄取到内存中。每个摄取的事件都作为内存文档存储在 memories_collection 参数配置的 内存集合中。这些文档包含从事件的文本内容中提取的小写关键字。

Considerations

使用内存服务时，请考虑以下行为：

  • 当您搜索内存时，该服务会返回关键字大量与查询关键字相交的文档。

  • 摄取是幂等的。如果重新引入会话，该服务将覆盖而不是复制其内存。

  • 检索执行关键字搜索，不需要嵌入模型、Google凭证或向量索引。因此，内存检索适用于任何MongoDB 部署。

索引指南

本节介绍集成MongoDB和 Google ADK 所需的索引，包括用于提高性能的推荐索引。

所需的 MongoDbToolset 索引

代理搜索的每个集合都需要以下索引：

  • 存储嵌入的字段上的MongoDB Vector Search索引，该字段索引为 vector 类型。如果您使用Atlas自动嵌入，请将字段索引为 autoEmbed 类型。

  • 存储要搜索的文本的字段上的MongoDB Search索引（如果您使用 mongodb_hybrid_search 工具）

MongoDbToolset 按名称读取这些索引，但不创建它们。要学习；了解如何创建这些索引，请参阅创建MongoDB Vector Search 索引和MongoDB Search 索引。

建议的服务索引

大多数读取和所有写入都使用MongoDB自动索引的 _id字段。但是，以下读取模式不使用 _id字段，并且需要进行全集合扫描，除非有索引：

  • 按应用、用户和会话读取会话事件，并按时间戳排序。

  • 按应用和用户搜索内存，并与关键字大量匹配。

默认下，MongoDbSessionService 和 MongoDbMemoryService 在首次使用时创建以下建议索引：

Collection
Index
索引字段和排序顺序

events

app_user_session_ts

(app_name, user_id, session_id, timestamp DESC, revision DESC)

sessions

app_user

(app_name, user_id)

memories

app_user_keywords

(app_name, user_id, keywords) (multikey)

如果将 ensure_indexes 参数设立为 False，则该服务不会创建这些建议的索引。

注意

索引创建具有幂等，因此您可以放心地将 ensure_indexes 参数设立为其默认值 True。此参数要求MongoDB用户对 sessions、events 和 memories 集合执行 createIndex动作。

权限指南

我们建议您不要使用单个管理员用户，而是使用两个单独的数据库用户，以将权限限制在每个组件所需的范围内。

下表描述了为两个数据库用户建议的最低权限配置：

数据库用户
使用的
最低权限

搜索用户（只读）

MongoDbToolset

find 在代理搜索的每个集合上

状态用户（读写）

MongoDbSessionService, MongoDbMemoryService

* find, insert, update, remove on the sessions and events collections
* find, insert, update on the app_states, user_states, and memories collections
* If you set ensure_indexes to True, add the createIndex action on the sessions, events, and memories collections

重要

上表中的权限是MongoDB操作，而不是Atlas内置角色。要授予权限，请使用这些操作为每个用户创建自定义角色，并将其范围限定为列出的集合。

其他资源

要学习；了解有关将 Google ADK 与MongoDB结合使用的更多信息，请参阅以下资源：

后退
OpenAI Agents SDK
来年
开始体验
给本页内容打分

在此页面上