Agents with Knowledge

Knowledge stores domain-specific content that can be added to the context of the agent to enable better decision making.

Agno has a generic knowledge solution that supports many forms of content.

See more details in the knowledge documentation.

The Agent can search this knowledge at runtime to make better decisions and provide more accurate responses. This searching on demand pattern is called Agentic RAG.

Example: Say we are building a Text2Sql Agent. We'll need to give the table schemas, column names, data types, example queries, etc to the agent to help it generate the best-possible SQL query.

It is not viable to put this all in the system message. Instead we store this information as knowledge and let the Agent query it at runtime.

Using this information, the Agent can then generate the best-possible SQL query. This is called dynamic few-shot learning.

Knowledge for Agents

Agno Agents use Agentic RAG by default, meaning when we provide knowledge to an Agent, it will search this knowledge base, at runtime, for the specific information it needs to achieve its task.

For example:

import asyncio

from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

db = PostgresDb(
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
    knowledge_table="knowledge_contents",
)

# Create Knowledge Instance
knowledge = Knowledge(
    name="Basic SDK Knowledge Base",
    description="Agno 2.0 Knowledge Implementation",
    contents_db=db,
    vector_db=PgVector(
        table_name="vectors",
        db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
        embedder=OpenAIEmbedder(),
    ),
)
# Add from URL to the knowledge base
asyncio.run(
    knowledge.ainsert(
        name="Recipes",
        url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
        metadata={"user_tag": "Recipes from website"},
    )
)

agent = Agent(
    name="My Agent",
    description="Agno 2.0 Agent Implementation",
    knowledge=knowledge,
    search_knowledge=True,
)

agent.print_response(
    "How do I make chicken and galangal in coconut milk soup?",
    markdown=True,
)

We can give our agent access to the knowledge base in the following ways:

We can set search_knowledge=True to add a search_knowledge_base() tool to the Agent. search_knowledge is True by default if you add knowledge to an Agent.
We can set add_knowledge_to_context=True to automatically add references from the knowledge base to the Agent's context, based on your user message. This is the traditional RAG approach.

Custom knowledge retrieval

If you need complete control over the knowledge base search, you can pass your own knowledge_retriever function with the following signature:

from typing import Optional
from agno.agent import Agent

def knowledge_retriever(agent: Agent, query: str, num_documents: Optional[int], **kwargs) -> Optional[list[dict]]:
  ...

Example of how to configure an agent with a custom retriever:

from typing import Optional
from agno.agent import Agent

def knowledge_retriever(agent: Agent, query: str, num_documents: Optional[int], **kwargs) -> Optional[list[dict]]:
  ...

agent = Agent(
    knowledge_retriever=knowledge_retriever,
    search_knowledge=True,
)

This function is called during search_knowledge_base() and is used by the Agent to retrieve references from the knowledge base.

Async retrievers are supported. Simply create an async function and pass it to the knowledge_retriever parameter.

Knowledge storage

Knowledge content is tracked in a "Contents DB" and vectorized and stored in a "Vector DB".

Contents database

The Contents DB is a database that stores the name, description, metadata and other information for any content you add to the knowledge base.

Below is the schema for the Contents DB:

Field	Type	Description
`id`	`str`	The unique identifier for the knowledge content.
`name`	`str`	The name of the knowledge content.
`description`	`str`	The description of the knowledge content.
`metadata`	`dict`	The metadata for the knowledge content.
`type`	`str`	The type of the knowledge content.
`size`	`int`	The size of the knowledge content. Applicable only to files.
`linked_to`	`str`	The name of the Knowledge instance this content belongs to.
`access_count`	`int`	The number of times this content has been accessed.
`status`	`str`	The status of the knowledge content.
`status_message`	`str`	The message associated with the status of the knowledge content.
`created_at`	`int`	The timestamp when the knowledge content was created.
`updated_at`	`int`	The timestamp when the knowledge content was last updated.
`external_id`	`str`	The external ID of the knowledge content. Used when external vector stores are used, like LightRAG.

This data is best displayed on the knowledge page of the AgentOS UI.

Vector databases

Vector databases store the embedding vectors for each chunk and power similarity search over the knowledge base. See Vector databases for supported providers and search types.

Adding contents

The typical way content is processed when being added to the knowledge base is:

Parse the content

A reader is used to parse the content based on the type of content that is being inserted

Chunk the information

The content is broken down into smaller chunks to ensure our search query returns only relevant results.

Embed each chunk

The chunks are converted into embedding vectors and stored in a vector database.

For example, to add a PDF to the knowledge base:

...
knowledge = Knowledge(
    name="Basic SDK Knowledge Base",
    description="Agno 2.0 Knowledge Implementation",
    vector_db=vector_db,
    contents_db=contents_db,
)

asyncio.run(
    knowledge.ainsert(
        name="CV",
        path="cookbook/07_knowledge/testing_resources/cv_1.pdf",
        metadata={"user_tag": "Engineering Candidates"},
    )
)

See more details on loading content.

Knowledge filters restrict searches using content metadata. For supported vector databases and usage, see the Knowledge Filters documentation.

Example: Agentic RAG Agent

Build a RAG Agent that answers questions from a PDF.

Set up the database

Use Postgres for both the contents and vector databases.

Install docker desktop and run Postgres on port 5532 using:

docker run -d \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e PGDATA=/var/lib/postgresql/data/pgdata \
  -v pgvolume:/var/lib/postgresql/data \
  -p 5532:5432 \
  --name pgvector \
  agnohq/pgvector:18

This docker container contains a general purpose Postgres database with the pgvector extension installed.

Install required packages:

uv pip install -U agno openai pgvector pypdf psycopg sqlalchemy

Set the OpenAI key

export OPENAI_API_KEY="your-openai-api-key"

On Windows PowerShell, use $env:OPENAI_API_KEY = "your-openai-api-key".

Do agentic RAG

Create a file agentic_rag.py with the following contents

agentic_rag.py

import asyncio
from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIResponses
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"

db = PostgresDb(
    db_url=db_url,
    knowledge_table="knowledge_contents",
)

knowledge = Knowledge(
    contents_db=db,
    vector_db=PgVector(
        table_name="recipes",
        db_url=db_url,
        embedder=OpenAIEmbedder(),
    )
)

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,
    knowledge=knowledge,
    markdown=True,
)
if __name__ == "__main__":
    asyncio.run(
        knowledge.ainsert(
            name="Recipes",
            url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
            metadata={"user_tag": "Recipes from website"}
        )
    )
    # Create and use the agent
    asyncio.run(
        agent.aprint_response(
            "How do I make chicken and galangal in coconut milk soup?",
            markdown=True,
        )
    )

Run the agent

python agentic_rag.py

Next Steps

Task	Guide
Let the model choose when to search, with LanceDB	Agentic RAG with LanceDB
Let the model choose when to search, with PgVector	Agentic RAG with PgVector
Retrieve before the first model call, with LanceDB	Traditional RAG with LanceDB
Retrieve before the first model call, with PgVector	Traditional RAG with PgVector