Integre o MongoDB com a framework Agno

Você pode integrar o MongoDB ao Agno, uma estrutura Python de código aberto para criar agentes de IA multimodais. Agno fornece duas integrações MongoDB :

banco de dados vetorial que armazena a base de conhecimento do seu agente e a recupera com o MongoDB Vector Search.
banco de dados de sessões e memória que persiste sessões de agente , memória de usuários, métricas e avaliações executadas em suas collections 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

Agno requer Python v3.9 ou posterior. Para instalar as versões mais recentes do Agno e 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 de cliente OpenAI, execute o seguinte comando:

pip install openai

Os exemplos do Custom configuration nesta página usam incorporações Voyage AI. Para instalar a biblioteca do cliente Voyage AI, execute o seguinte comando:

pip install voyageai

Variáveis de ambiente

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

Connection string: defina MONGODB_URI como a string de conexão para o MongoDB deployment.
Chave API do modelo: defina OPENAI_API_KEY ou VOYAGE_API_KEY como a chave API do fornecedor do modelo.

Banco de dados vetorial

A classe MongoVectorDb implementa a interface do banco de dados vetorial Agno com o MongoDB Vector Search. Para fornecer uma pesquisa semântica de agente em seus documentos, passe uma instância dessa 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 classes MongoDB

Agno nomeia ambas as classes MongoDB MongoDb, mas as importa de módulos diferentes. Importe a classe do banco de dados vetorial de agno.vectordb.mongodb e a classe do banco de dados de agno.db.mongo. Para evitar uma colisão de nome, o Agno também exporta a classe do 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 collection que armazena suas incorporações e sua string de conexão MongoDB . O exemplo a seguir cria uma base de conhecimento, adiciona um documento e fornece a um agente acesso aos dados:

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)

O exemplo a seguir habilita a pesquisa híbrida, usa a Voyage AI para gerar incorporações em vez do padrão OpenAI e especifica um nome de índice do 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)

Se você especificar um incorporador, o Agno usará o número de dimensões que o incorporador produz ao criar o índice do MongoDB Vector Search . O dicionário request_params passa argumentos de palavra-chave específicos do fornecedor para a chamada de incorporação. Para o Voyage AI, output_dimension controla o tamanho do vetor retornado para modelos que suportam dimensões variáveis.

Quando você cria um objetoKnowledge, o Agno verifica se a collection já existe. Caso contrário, o Agno cria a coleção e o índice do MongoDB Vector Search . Se a collection existir, o Agno não verificará se o índice existe, mesmo que você o exclua separadamente.

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

Parâmetros do banco de dados vetorial

Use esses parâmetros para configurar o banco de dados vetorial.

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 suas incorporações.
`db_url`	Opcional	A string de conexão para sua deployment do MongoDB . Padrão `mongodb://localhost:27017/` é. Para saber mais sobre como localizar sua string de conexão, consulte Conectar-se a um cluster por meio de bibliotecas de clientes.
`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 incorporação que o Agno usa para incorporar seus documentos e queries. O padrão é `OpenAIEmbedder()`.
`distance_metric`	Opcional	A função de similaridade que o índice do MongoDB Vector Search utiliza. Somente 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ânticas. 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 recíproca de fusão da classificação. O padrão é `60`.
`search_index_name`	Opcional	O nome do índice MongoDB Vector Search em sua coleção. O padrão é `vector_index_1`.
`wait_until_index_ready_in_seconds`	Opcional	Se o Agno aguarda, depois de criar o índice do MongoDB Vector Search , que o nome do índice apareça nos índices de pesquisa da collection. Defina esse parâmetro como um número positivo para aguardar ou para `None` para ignorar a espera. Os métodos assíncronos usam o valor como tempo limite, em segundos. O padrão é `3`.
`wait_after_insert_in_seconds`	Opcional	O tempo, em segundos, que o Agno espera depois de 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 as operações de gravação com suporte. O padrão é `True`.
`cosmos_compatibility`	Opcional	Se o Agno cria índices no formato do Azure Cosmos DB para MongoDB vCore em vez do formato do MongoDB Vector Search . O padrão é `False`.
`name`, `description` , `id`	Opcional	Os metadados de identificação para a instância do banco de dados de vetor. Se você não especificar `id`, o Agno o derivará da string de conexão, do nome do banco de dados e do nome da collection.

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 somente se você gerenciar documentos fora de um objetoKnowledge.

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

Método	Descrição
`search(query, limit, filters, min_score, user_id)`	Incorpora `query` e retorna até `limit` documentos correspondentes. 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 filtros de metadados. Se você passar uma lista de expressões de filtro do Agno, o Agno registrará um aviso e não aplicará filtros porque a integração do MongoDB não oferece suporte a eles.
`insert(content_hash, documents, filters, user_id)`	Incorpora cada documento em `documents` e insere os documentos em sua coleção. Agno deriva o valor `_id` de cada documento de um hash do conteúdo do documento .
`upsert(content_hash, documents, filters, user_id)`	Substitui os documentos que compartilham `content_hash` e, em seguida, insere os documentos em `documents`. Use este método para atualizar um documento cujo conteúdo foi alterado.
`delete()`	Exclui todos os documento da sua collection, mas mantém a collection e seu índice do MongoDB Vector Search .
`delete_by_id(id)`	Exclui o documento com o valor `_id` especificado.
`delete_by_name(name)`	Exclui os documentos com o valor `name` especificado.
`delete_by_metadata(metadata)`	Exclui os documentos cujo campo `meta_data` corresponde aos pares de chave-valor especificados.
`drop()`	Descarta sua coleção e o índice do MongoDB Vector Search .
`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 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 de um agente, as gravações, as métricas e as execuções de avaliação de um agente no MongoDB, passe uma instância dessa classe para o parâmetro db de um objetoAgent, 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ão no MongoDB e inclui esse histórico no contexto do modelo:

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)

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

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)

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

Database Parameters

Use estes parâmetros para configurar o banco de dados.

A classe MongoDb aceita os seguintes parâmetros:

Parâmetro	necessidade	Descrição
`db_url`	Condicional	A string de conexão para sua deployment 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 ignorará `db_url`.
`db_name`	Opcional	O nome do banco de dados que contém as collections. O padrão é `agno`.
`session_collection`	Opcional	O nome da coleção que armazena as sessões do agente, da equipe e do fluxo de trabalho. O padrão é `agno_sessions`.
`runs_collection`	Opcional	O nome da collection que armazena é executada, 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 coleção de sessão, como `agent_sessions_runs`.
`memory_collection`	Opcional	O nome da coleção que armazena as memória 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 collection que armazena a avaliação é executada. 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 extensão . Padrão para `agno_traces` e `agno_spans`.
`schedules_collection`, `schedule_runs_collection`	Opcional	Os nomes das coleções que armazenam agendamentos e agendamentos de execuções. Padrão para `agno_schedules` e `agno_schedule_runs`.
`learnings_collection`	Opcional	O nome da coleção que armazena aprendizados. O padrão é `agno_learnings`.
`id`	Opcional	O identificador da instância do banco de dados . Se você não especificar este parâmetro, o Agno o derivará da string de conexão e do nome do banco de dados .

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

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

índice de pesquisa

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

O índice utiliza a seguinte definição, onde numDimensions corresponde ao número de dimensões que seu incorporador 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 ele possa fazer o escopo das pesquisas para os documentos de um único usuário final.

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

Recursos adicionais

Para saber mais sobre como usar o Agno com o MongoDB, consulte os seguintes recursos:

Referênciado Agno MongoDB Vector Store
Referênciado banco de dados Agno MongoDB
Documentação doAgno Knowledge
Repositório doAgno GitHub

Voltar

Mastra

Começar