将MongoDB与 Agno 框架集成

您可以将MongoDB与 Agno 集成，Agno 是一个用于构建多模式AI代理的开源Python框架。 Agno 提供两种MongoDB集成：

Vector数据库，用于存储客服人员的知识库并使用MongoDB Vector Search 进行检索。
会话和内存数据库，用于在MongoDB集合中持久保存代理会话、用户内存、指标和评估运行。

您可以单独使用任一集成，也可以在同一代理中同时使用这两种集成。

开始体验

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

安装

Agno 需要Python v3.9 或更高版本。要安装最新的 Agno 和PyMongo版本，运行以下命令：

pip install agno pymongo

本页上的示例使用 OpenAI 模型，Agno默认使用该模型。要安装 OpenAI客户端库，运行以下命令：

pip install openai

本页上的 Custom configuration 示例使用 Voyage AI嵌入。要安装 Voyage AI客户端库，运行以下命令：

pip install voyageai

环境变量

在运行此页面上的示例之前，设立以下环境变量：

连接字符串：将 MONGODB_URI 设置为MongoDB 部署的连接字符串。
模型API密钥：将 OPENAI_API_KEY 或 VOYAGE_API_KEY 设置为模型提供商程序的API密钥。

向量数据库

MongoVectorDb 类使用MongoDB Vector Search 实现 Agno 矢量数据库接口。要对文档进行代理语义搜索，请将此类的实例传递给 Agno Knowledge对象的 vector_db 参数，然后将该对象传递给代理的 knowledge 参数。

重要

MongoDB类名

Agno 将这两个MongoDB类命名为 MongoDb，但从不同的模块导入它们。从 agno.vectordb.mongodb 导入矢量数据库类，从 agno.db.mongo 导入数据库类。为了避免名称冲突，Agno 还将矢量数据库类导出为 MongoVectorDb。本页上的示例使用该别名。

选择 Basic initialization标签页以查看最小配置示例，或选择 Custom configuration标签页以查看如何使用自定义设置来配置集成。

要初始化向量数据库，请指定存储嵌入和MongoDB连接字符串的集合。以下示例创建了一个知识库，添加了一个文档，并授予代理访问权限数据的权限：

import os
from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge
from 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)

以下示例启用混合搜索，使用 Voyage AI生成嵌入而不是 OpenAI默认嵌入，并指定MongoDB Vector Search索引名称：

import os
from agno.agent import Agent
from agno.knowledge.embedder.voyageai import VoyageAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.mongodb import MongoVectorDb
from 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)

如果您指定嵌入器，Agno 将使用嵌入器在创建MongoDB Vector Search索引时生成的维数。 request_params 字典将特定于提供程序的关键字参数传递给嵌入调用。对于 Voyage AI，output_dimension 控制支持可变维度的模型返回的向量的大小。

当您创建 Knowledge对象时，Agno 会验证该集合是否已存在。如果没有，Agno 将创建集合和MongoDB Vector Search索引。如果集合存在，Agno 不会检查索引是否存在，即使您单独删除索引也是如此。

创建索引后，Agno 会等待索引出现在集合中。但是，它不会验证索引状态，因此在索引构建完成后，立即运行的查询可能不会返回任何结果。

向量数据库参数

使用这些参数配置向量数据库。

MongoVectorDb 类接受以下参数：

Parameter	必要性	说明
`collection_name`	必需	存储文档及其嵌入的集合的名称。
`db_url`	Optional	MongoDB 部署的连接字符串。默认为`mongodb://localhost:27017/` 。要学习；了解有关查找连接字符串的更多信息，请参阅通过客户端库连接到集群。
`client`	Optional	现有的 `MongoClient`实例。如果指定此参数，Agno 将忽略 `db_url`。
`database`	Optional	保存该集合的数据库的名称。默认为 `agno`。
`embedder`	Optional	Agno 用于嵌入文档和查询的嵌入模型。默认为 `OpenAIEmbedder()`。
`distance_metric`	Optional	MongoDB Vector Search索引使用的相似度函数。目前仅支持默认值 `Distance.cosine`。
`search_type`	Optional	检索策略。接受 `SearchType.vector` 或 `SearchType.hybrid`。默认为 `SearchType.vector`。
`hybrid_vector_weight`	Optional	混合搜索应用于语义结果的权重。默认为 `0.5`。
`hybrid_keyword_weight`	Optional	混合搜索应用于关键字结果的权重。默认为 `0.5`。
`hybrid_rank_constant`	Optional	混合搜索在计算倒数排名融合分数之前添加到每个排名的常量。默认为 `60`。
`search_index_name`	Optional	集合上的MongoDB Vector Search索引的名称。默认为 `vector_index_1`。
`wait_until_index_ready_in_seconds`	Optional	创建MongoDB Vector Search索引后，Agno 是否等待索引名称出现在集合的搜索索引中。将此参数设置为正数以等待，或设置为 `None` 以跳过等待。异步方法使用该值作为超时（以秒为单位）。默认为 `3`。
`wait_after_insert_in_seconds`	Optional	Agno 插入文档后的等待时间（以秒为单位）。默认为 `3`。
`max_pool_size`	Optional	驾驶员连接池的最大连接数。默认为 `100`。
`retry_writes`	Optional	驾驶员是否重试支持的写入操作。默认为 `True`。
`cosmos_compatibility`	Optional	Agno 是否以Azure Cosmos DB for MongoDB vCore 格式而不是MongoDB Vector Search 格式创建索引。默认为 `False`。
`name`, `description` , `id`	Optional	矢量数据库实例的标识元数据。如果您不指定 `id`，Agno 会从连接字符串、数据库名称和集合名称中派生。

向量数据库方法

当您向知识库添加内容或代理搜索知识库时，Knowledge 类会调用以下方法。仅当您在 Knowledge对象之外管理文档时才直接调用这些方法。

要将写入或搜索操作限制为一个用户的文档，请将 user_id 值传递给操作方法。

方法	说明
`search(query, limit, filters, min_score, user_id)`	嵌入 `query` 并返回最多 `limit` 个匹配文档。如果将 `search_type`设立为 `SearchType.hybrid`，Agno 还会运行关键字搜索并合并两个结果集。 `filters` 参数接受元数据筛选器字典。如果改为传递 Agno过滤表达式列表，Agno 会记录警告并且不会应用筛选器，因为MongoDB集成不支持筛选器。
`insert(content_hash, documents, filters, user_id)`	将每个文档嵌入 `documents` 中并将这些文档插入到您的集合中。 Agno 从文档内容的哈希值中获取每个文档的 `_id` 值。
`upsert(content_hash, documents, filters, user_id)`	替换股票`content_hash` 的文档，然后将文档插入 `documents` 中。使用此方法可更新内容已更改的文档。
`delete()`	删除集合中的每个文档，但保留集合及其MongoDB Vector Search索引。
`delete_by_id(id)`	删除具有指定 `_id` 值的文档。
`delete_by_name(name)`	删除具有指定 `name` 值的文档。
`delete_by_metadata(metadata)`	删除 `meta_data`字段与指定键值对匹配的文档。
`drop()`	删除您的集合及其MongoDB Vector Search索引。
`exists()`	如果您的集合存在，则返回 `True`。
`get_count()`	返回集合中的文档数。

提示

异步方法

上表中描述的以下方法都有一个相应的异步方法：

search()：使用 async_search()
insert()：使用 async_insert()
upsert()：使用 async_upsert()
drop()：使用 async_drop()
exists()：使用 async_exists()

会话和内存数据库

agno.db.mongo 模块中的 MongoDb 类实现了 Agno数据库接口。要在MongoDB中持久保存助手的会话、用户记忆、指标和评估运行，请将此类的实例传递给 Agent、Team 或 Workflow 对象的 db对象。

选择 Basic initialization标签页以查看最小配置示例，或选择 Custom configuration标签页以查看如何使用自定义设置来配置集成。

要初始化数据库，请指定MongoDB连接字符串。以下示例创建一个代理，将其会话历史记录存储在MongoDB中，并将该历史记录包含在模型上下文中：

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

以下示例指定数据库名称以及存储会话、内存和指标的集合的名称：

import os
from agno.agent import Agent
from 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 会在您配置的每个集合首次写入时创建该集合。

Database Parameters

使用这些参数配置数据库。

MongoDb 类接受以下参数：

Parameter	必要性	说明
`db_url`	可选的	MongoDB 部署的连接字符串。如果未指定 `db_client`，则为必填项。
`db_client`	可选的	现有的 `MongoClient`实例。如果未指定 `db_url`，则为必填项。如果同时指定两者，Agno 将忽略 `db_url`。
`db_name`	Optional	保存集合的数据库的名称。默认为 `agno`。
`session_collection`	Optional	存储代理、团队和工作流会话的集合的名称。默认为 `agno_sessions`。
`runs_collection`	Optional	存储运行的集合的名称，每次运行一个文档。默认为 `agno_runs`。如果您指定 `session_collection` 但未指定此参数，Agno 将根据您的会话集合名称创建名称，例如 `agent_sessions_runs`。
`memory_collection`	Optional	存储用户记忆的集合的名称。默认为 `agno_memories`。
`metrics_collection`	Optional	存储聚合使用指标的集合的名称。默认为 `agno_metrics`。
`eval_collection`	Optional	存储评估运行的集合的名称。默认为 `agno_eval_runs`。
`knowledge_collection`	Optional	存储知识内容元数据的集合的名称。默认为 `agno_knowledge`。
`traces_collection`, `spans_collection`	Optional	存储跟踪和跨度的集合的名称。默认为 `agno_traces` 和 `agno_spans`。
`schedules_collection`, `schedule_runs_collection`	Optional	存储计划和安排运行的集合的名称。默认为 `agno_schedules` 和 `agno_schedule_runs`。
`learnings_collection`	Optional	存储学习内容的集合的名称。默认为 `agno_learnings`。
`id`	Optional	数据库实例的标识符。如果您不指定此参数，Agno 将从连接字符串和数据库名称中派生。

当代理运行时，Agno 会自动读取和写入本节中描述的会话、内存和指标集合。 Agno 会在第一次需要时创建每个集合。您也可以直接在 MongoDb实例上调用方法，如下所示：

upsert_session() 和 get_sessions() 读取和写入会话。
upsert_user_memory() 写入单个用户内存。
get_metrics() 读取聚合使用情况指标。
upsert_sessions() 和 upsert_memories() 在单个操作中写入许多记录，例如当您将现有会话历史记录迁移到MongoDB。
close() 释放客户端连接。在应用程序关闭时调用此方法。

搜索索引

Agno 首次创建向量集合时，还会在该集合上创建MongoDB Vector Search索引。索引名称是 search_index_name 参数的值，默认为 vector_index_1。您也可以手动创建或检查此索引。要学习；了解更多信息，请参阅创建MongoDB Vector Search 索引。

索引使用以下定义，其中 numDimensions 与嵌入器生成的维数匹配，similarity 与 distance_metric 值匹配：

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

Agno 将 user_id字段作为过滤字段进行索引，以便将搜索范围限定为单个最终用户的文档。

混合搜索不需要MongoDB搜索索引。 Agno 将其关键字搜索作为对 content字段的正则表达式查询运行，然后使用倒数排名融合将这些结果与MongoDB Vector Search 结果合并。

其他资源

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