Integre o MongoDB com o Agno framework

Você pode integrar o MongoDB com o Agno, um framework Python de código aberto para a criação de agente de IA multimodais. O Agno oferece duas integrações com o MongoDB:

Banco de dados vetorial que armazena a base de conhecimento do seu agente e a recupera com a pesquisa vetorial do MongoDB.
Banco de dados de sessão e memória que persiste sessões de agente, memórias de usuário, métricas e execuções de avaliação em suas coleção do MongoDB.

Você pode usar qualquer integração por conta própria ou pode usar ambas no mesmo agente.

Começar

Para concluir um tutorial que configura o Agno para usar o MongoDB, consulte Introdução à integração do MongoDB Agno.

Instalação

O Agno exige Python versão3.9 ou versão posterior. Para instalar as últimas versões do Agno e do PyMongo, execute o seguinte comando:

pip install agno pymongo

Os exemplos nesta página usam modelos OpenAI, que o Agno usa por padrão. Para instalar a biblioteca cliente OpenAI, execute o seguinte comando:

pip install openai

Os Custom configuration exemplo nesta página usam embedding do Voyage AI. Para instalar a biblioteca cliente do Voyage AI, execute o seguinte comando:

pip install voyageai

Variáveis de ambiente

Antes de executar os exemplo nesta página, defina as seguintes variáveis de ambiente:

String de conexão: Defina MONGODB_URI como a string de conexão para sua implantação do MongoDB.
Chave de API do modelo: Defina OPENAI_API_KEY ou VOYAGE_API_KEY como a chave de API do seu provedor de modelo.

banco de dados vetorial

A classe MongoVectorDb implementa a interface do banco de dados vetorial Agno com a pesquisa vetorial do MongoDB. Para dar a um agente pesquisa semântica sobre seus documentos, passe uma instância desta classe para o parâmetro vector_db de um objeto Agno Knowledge e, em seguida, passe esse objeto para o parâmetro knowledge do seu agente.

Importante

Nomes de classe do MongoDB

O Agno nomeia ambas as classes do MongoDB como MongoDb, mas as importa de módulos diferentes. Importe a classe de banco de dados vetorial de agno.vectordb.mongodb e a classe de banco de dados de agno.db.mongo. Para evitar uma colisão de nomes, o Agno também exporta a classe de banco de dados vetorial como MongoVectorDb. Os exemplos nesta página usam esse alias.

Selecione a aba Basic initialization para visualizar um exemplo de configuração mínima, ou selecione a aba Custom configuration para ver como configurar a integração com configurações personalizadas.

Para inicializar o banco de dados vetorial, especifique a coleção que armazena seus embedding e sua string de conexão do MongoDB. O exemplo a seguir cria uma Base de Conhecimento, adiciona um documento e dá a um agente acesso aos dados:

import osfrom agno.agent import Agentfrom agno.knowledge.knowledge import Knowledgefrom 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)

O exemplo a seguir habilita a pesquisa híbrida, usa o Voyage AI para gerar embeddings em vez do padrão da OpenAI e especifica um nome de índice de pesquisa vetorial do MongoDB:

import osfrom agno.agent import Agentfrom agno.knowledge.embedder.voyageai import VoyageAIEmbedderfrom agno.knowledge.knowledge import Knowledgefrom agno.vectordb.mongodb import MongoVectorDbfrom 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)

Se você especificar um embedder, o Agno usará o número de dimensões que o embedder produz ao criar o índice de pesquisa vetorial do MongoDB. O dicionário request_params passa argumentos de palavra-chave específicos do provedor para chamar de embedding. Para Voyage AI, output_dimension controla o tamanho do vetor retornado para modelos que suportam dimensões variáveis.

Ao criar um objeto Knowledge, o Agno verifica se a coleção já existe. Se não o fizer, Agno cria a coleção e o índice de pesquisa vetorial do MongoDB. Se a coleção existir, o Agno não verifica se o índice existe, mesmo que você o tenha excluído separadamente.

Depois de criar o índice, Agno aguarda até que o índice apareça na coleção. No entanto, não verifica o status do índice, portanto, uma query que executa imediatamente depois pode não retornar resultados enquanto o índice termina de ser criado.

A classe MongoVectorDb aceita os seguintes parâmetros:

Parâmetro	necessidade	Descrição
`collection_name`	Obrigatório	O nome da coleção que armazena seus documentos e seus embeddings.
`db_url`	Opcional	A string de conexão para sua implantação do MongoDB. O padrão é `mongodb://localhost:27017/`. Para saber mais sobre como encontrar sua string de conexão, consulte Conectar a um cluster via bibliotecas cliente.
`client`	Opcional	Uma instância `MongoClient` existente. Se você especificar este parâmetro, o Agno ignorará `db_url`.
`database`	Opcional	O nome do banco de dados que contém a coleção. O padrão é `agno`.
`embedder`	Opcional	O modelo de embedding que o Agno usa para fazer embedding de seus documentos e queries. O padrão é `OpenAIEmbedder()`.
`distance_metric`	Opcional	A função de similaridade que o índice de pesquisa vetorial do MongoDB usa. Apenas o valor padrão, `Distance.cosine`, é suportado atualmente.
`search_type`	Opcional	A estratégia de recuperação. Aceita `SearchType.vector` ou `SearchType.hybrid`. O padrão é `SearchType.vector`.
`hybrid_vector_weight`	Opcional	O peso que a pesquisa híbrida aplica aos resultados semânticos. O padrão é `0.5`.
`hybrid_keyword_weight`	Opcional	O peso que a pesquisa híbrida aplica aos resultados de palavras-chave. O padrão é `0.5`.
`hybrid_rank_constant`	Opcional	A constante que a pesquisa híbrida adiciona a cada classificação antes de calcular a pontuação de fusão de classificação recíproca. O padrão é `60`.
`search_index_name`	Opcional	O nome do índice do MongoDB pesquisa vetorial na sua coleção. O padrão é `vector_index_1`.
`wait_until_index_ready_in_seconds`	Opcional	Se o Agno aguarda, após criar o índice de pesquisa do MongoDB pesquisa vetorial, que o nome do índice apareça nos índices de pesquisa da coleção. Defina este parâmetro como um número positivo para aguardar ou como `None` para ignorar a espera. Os métodos assíncronos usam o valor como um tempo limite, em segundos. O padrão é `3`.
`wait_after_insert_in_seconds`	Opcional	O tempo, em segundos, que o Agno aguarda após inserir documentos. O padrão é `3`.
`max_pool_size`	Opcional	O número máximo de conexões no pool de conexões do driver. O padrão é `100`.
`retry_writes`	Opcional	Se o driver tenta novamente operações de gravar suportadas. O padrão é `True`.
`cosmos_compatibility`	Opcional	Se o Agno cria índices no formato Azure Cosmos DB para MongoDB vCore em vez do formato de pesquisa vetorial do MongoDB. O padrão é `False`.
`name`, `description` , `id`	Opcional	Os metadados de identificação para a instância do banco de dados vetorial. Se você não especificar `id`, o Agno o deriva da string de conexão, do nome do banco de dados e do nome da coleção.

Métodos de banco de dados vetorial

A classe Knowledge chama os seguintes métodos quando você adiciona conteúdo a uma Base de Conhecimento ou quando um agente a pesquisa. Chame esses métodos diretamente apenas se você gerenciar documentos fora de um objeto Knowledge.

Para limitar uma operação de gravar ou pesquisa aos documentos de um usuário, passe um valor user_id ao método de operação.

Método	Descrição
`search(query, limit, filters, min_score, user_id)`	Incorpora `query` e retorna até `limit` documento correspondente. Se você definir `search_type` como `SearchType.hybrid`, o Agno também executará uma pesquisa por palavra-chave e mesclará os dois conjuntos de resultados. O parâmetro `filters` aceita um dicionário de filtro de metadados. Se você passar uma lista de expressões de filtro do Agno, o Agno fará log de um aviso e não aplicará nenhum filtro porque a integração do MongoDB não os suporta.
`insert(content_hash, documents, filters, user_id)`	Incorpora cada documento em `documents` e insere os documentos na sua coleção. O Agno deriva o valor `_id` de cada documento a partir de um hash do conteúdo do documento.
`upsert(content_hash, documents, filters, user_id)`	Substitui os documentos que compartilham `content_hash`, então insere os documentos em `documents`. Use este método para atualizar um documento cujo conteúdo foi alterado.
`delete()`	Exclui todos os documentos da sua coleção, mas mantém a coleção e seu índice de pesquisa vetorial do MongoDB.
`delete_by_id(id)`	Excluir o documento com o valor `_id` especificado.
`delete_by_name(name)`	Excluir os documentos com o valor `name` especificado.
`delete_by_metadata(metadata)`	Excluir os documento cujo campo `meta_data` corresponde aos pares chave-valor especificados.
`drop()`	Descartar sua coleção e seu índice do MongoDB pesquisa vetorial.
`exists()`	Retorna `True` se sua coleção existir.
`get_count()`	Retorna o número de documentos em sua coleção.

Dica

Métodos assíncronos

Os seguintes métodos descritos na tabela anterior têm, cada um, um método assíncrono correspondente:

search(): Usar async_search()
insert(): Usar async_insert()
upsert(): Usar async_upsert()
drop(): Usar async_drop()
exists(): Usar async_exists()

Banco de dados de sessão e memória

A classe MongoDb no módulo agno.db.mongo implementa a interface de banco de dados Agno. Para persistir as sessões, memórias de usuário, métricas e execuções de avaliação de um agente no MongoDB, passe uma instância desta classe para o parâmetro db de um objeto Agent, Team ou Workflow.

Para inicializar o banco de dados, especifique sua string de conexão do MongoDB. O exemplo a seguir cria um agente que armazena seu histórico de sessões no MongoDB e inclui esse histórico no contexto do modelo:

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

O exemplo a seguir especifica o nome do banco de dados e os nomes das coleção que armazenam sessões, memórias e métricas:

import osfrom agno.agent import Agentfrom 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)

O Agno cria cada coleção que você configura na primeira vez que ele gravar nessa coleção.

A classe MongoDb aceita os seguintes parâmetros:

Parâmetro	necessidade	Descrição
`db_url`	Condicional	A string de conexão para sua implantação do MongoDB. Obrigatório se você não especificar `db_client`.
`db_client`	Condicional	Uma instância `MongoClient` existente. Obrigatório se você não especificar `db_url`. Se você especificar ambos, o Agno ignora `db_url`.
`db_name`	Opcional	O nome do banco de dados que contém as coleções. O padrão é `agno`.
`session_collection`	Opcional	O nome da coleção que armazena sessões de agente, equipe e fluxo de trabalho. O padrão é `agno_sessions`.
`runs_collection`	Opcional	O nome da coleção que armazena execuções, com um documento por execução. O padrão é `agno_runs`. Se você especificar `session_collection`, mas não este parâmetro, o Agno criará o nome a partir do nome da sua coleção de sessões, como `agent_sessions_runs`.
`memory_collection`	Opcional	O nome da coleção que armazena memórias do usuário. O padrão é `agno_memories`.
`metrics_collection`	Opcional	O nome da coleção que armazena métricas de uso agregadas. O padrão é `agno_metrics`.
`eval_collection`	Opcional	O nome da coleção que armazena as executar de avaliação. O padrão é `agno_eval_runs`.
`knowledge_collection`	Opcional	O nome da coleção que armazena metadados de conteúdo de conhecimento. O padrão é `agno_knowledge`.
`traces_collection`, `spans_collection`	Opcional	Os nomes das coleções que armazenam rastreamentos e intervalos. Por padrão, `agno_traces` e `agno_spans`.
`schedules_collection`, `schedule_runs_collection`	Opcional	Os nomes das coleções que armazenam agendar e agendar executar. Padrão para `agno_schedules` e `agno_schedule_runs`.
`learnings_collection`	Opcional	O nome da coleção que armazenar aprendizados. O padrão é `agno_learnings`.
`id`	Opcional	O identificador da instância do banco de dados. Se você não especificar esse parâmetro, o Agno o derivará da string de conexão e do nome do banco de dados.

À medida que seu agente executar, o Agno lê e gravar automaticamente nas coleções de sessão, memória e métricas descritas nesta seção. O Agno cria cada coleção na primeira vez que ela é necessária. Você também pode chamar métodos diretamente na sua instância MongoDb, como os seguintes:

upsert_session() e sessões de leitura e gravação get_sessions().
upsert_user_memory() grava uma única memória de usuário.
get_metrics() lê métricas de uso agregadas.
upsert_sessions() e upsert_memories() gravar muitos registros em uma única operação, como quando você migra o histórico de sessões existente para o MongoDB.
close() libera a conexão do cliente. Chame este método quando seu aplicativo for encerrado.

índice de pesquisa

Na primeira vez que o Agno cria sua coleção de vetores, ele também cria um índice de pesquisa vetorial do MongoDB na coleção. O nome do índice é o valor do parâmetro search_index_name, que tem como padrão vector_index_1. Você também pode criar ou inspecionar esse índice manualmente. Para saber mais, consulte Criar um índice de pesquisa vetorial do MongoDB.

O índice usa a seguinte definição, onde numDimensions corresponde ao número de dimensões que seu embedder produz e similarity corresponde ao seu valor distance_metric:

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

O Agno indexa o campo user_id como um campo de filtro para que possa limitar as pesquisas aos documento de um único usuário final.

A pesquisa híbrida não requer um índice do MongoDB Search. O Agno executa sua pesquisa por palavra-chave como uma query de expressão regular no campo content e, em seguida, combina esses resultados com os resultados da pesquisa vetorial MongoDB usando a fusão de classificação recíproca.