Get Started with the MongoDB Agno Integration

Install dependencies.

Run the following commands in your terminal to create a new directory named agno-mongodb-project and install the required dependencies:

mkdir agno-mongodb-project
cd agno-mongodb-project
pip install agno pymongo openai python-dotenv pypdf

Set your environment variables.

In your agno-mongodb-project directory, create a .env file and add the following code:

OPENAI_API_KEY="<openai-api-key>"
MONGODB_URI="<connection-string>"

Replace <connection-string> with the connection string for your Atlas cluster or local Atlas deployment.

mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net

mongodb://localhost:<port-number>/?directConnection=true

Create a project file.

In your agno-mongodb-project directory, create a file named main.py. Add the following code to this file to load your environment variables:

import os
from dotenv import load_dotenv
from agno.agent import Agent
from agno.db.mongo import MongoDb
from agno.knowledge.knowledge import Knowledge
from agno.models.openai import OpenAIChat
from agno.vectordb.mongodb import MongoVectorDb
load_dotenv()

In future steps, you add code to this file to build your knowledge base and assistant.

Configure MongoDB as the vector store.

Add the following code to configure a MongoDB-backed vector store for your knowledge base:

vector_db = MongoVectorDb(
    collection_name="agent_knowledge",
    db_url=os.environ["MONGODB_URI"],
    database="agno",
)
knowledge = Knowledge(vector_db=vector_db)

The preceding code creates a MongoVectorDb instance and passes it to the vector_db parameter of a Knowledge object. Because this is the first time you're using the agent_knowledge collection, Agno creates it along with an MongoDB Vector Search index named vector_index_1.

The index should take about one minute to build. While it builds, the index is in an initial sync state. When it finishes building, you can start querying the data in your collection.

Load and store data.

Add the following code to your main.py file to load a PDF file containing Thai recipes into your knowledge base:

knowledge.insert(
    name="Recipes",
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
)

Agno downloads the file, splits it into chunks, generates an embedding for each chunk with the default OpenAI embedder, and writes the results to your collection.

Run a semantic search query.

Add the following code to your main.py file to query your knowledge base's vector database directly, before connecting it to an agent. This example searches for the three chunks most relevant to a question about green curry:

results = vector_db.search(query="How do I make a green curry?", limit=3)
for doc in results:
    print(f"[{doc.name}] {doc.content[:80]}")

The results include the recipe chunks that are most semantically relevant to the query, ranked by similarity score.

Define the assistant.

Add the following code to your main.py file to configure a MongoDb instance for session storage, and then create an agent that uses this session store and the knowledge base configured in the previous section:

db = MongoDb(
    db_url=os.environ["MONGODB_URI"],
    db_name="agno",
)
agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    knowledge=knowledge,
    db=db,
    search_knowledge=True,
    add_history_to_context=True,
    num_history_runs=5,
    instructions=[
        "You are a helpful cooking assistant.",
        "Answer questions using only the recipes in your knowledge base.",
        "If the knowledge base does not contain a relevant answer, say so clearly.",
    ],
)

Run the assistant across two conversation turns.

Add the following code to your main.py file to send two messages to the agent:

SESSION_ID = "cooking-session-001"
# First turn
agent.print_response(
    "My favorite Thai dish is massaman curry.",
    session_id=SESSION_ID,
)
# Second turn
agent.print_response(
    "How do I make my favorite dish?",
    session_id=SESSION_ID,
)

The agent retrieves the most relevant recipe chunks from your knowledge base on each turn. Because both calls use the same session_id value, Agno also retrieves data from the prior response. Agno retrieves the session metadata from the agno_sessions collection and the message content from the agno_runs collection. If you omit session_id or pass a different value on the second call, Agno starts a new session and the agent has no record of the first turn.