> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents with Knowledge

> Store domain-specific content that agents search at runtime, the Agentic RAG pattern.

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

> [!NOTE]
>
> Agno has a generic knowledge solution that supports many forms of content.
>
> See more details in the [knowledge](https://agno-v2.mintlify.site/knowledge/overview.md) 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.

> [!TIP]
>
> 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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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.

> [!TIP]
>
> 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](https://os.agno.com/knowledge).

### Vector databases

Vector databases store the embedding vectors for each chunk and power similarity search over the knowledge base. See [Vector databases](https://agno-v2.mintlify.site/knowledge/concepts/vector-db.md) for supported providers and search types.

### Adding contents

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

**1. Parse the content**

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

**2. Chunk the information**

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

**3. 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:

```python theme={null}
...
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"},
    )
)
```

> [!TIP]
>
> See more details on [loading
> content](https://agno-v2.mintlify.site/examples/knowledge/getting-started/loading-content.md).

> [!NOTE]
>
> Knowledge filters restrict searches using content metadata. For supported
> vector databases and usage, see the [Knowledge Filters
> documentation](https://agno-v2.mintlify.site/knowledge/concepts/filters/overview.md).

## Example: Agentic RAG Agent

Build a **RAG Agent** that answers questions from a PDF.

**1. Set up the database**

Use `Postgres` for both the contents and vector databases.

Install [docker desktop](https://docs.docker.com/desktop/install/mac-install/) and run **Postgres** on port **5532** using:

```bash theme={null}
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
```

> [!NOTE]
>
> This docker container contains a general purpose Postgres database with the `pgvector` extension installed.

Install required packages:

```bash Mac theme={null}
uv pip install -U agno openai pgvector pypdf psycopg sqlalchemy
```

```bash Windows theme={null}
uv pip install -U agno openai pgvector pypdf psycopg sqlalchemy
```

**2. Do agentic RAG**

Create a file `agentic_rag.py` with the following contents

```python agentic_rag.py theme={null}
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,
        )
    )
```

**3. Run the agent**

Run the agent

```bash theme={null}
python agentic_rag.py
```

## Next Steps

| Task | Guide |
| - | - |
| Let the model choose when to search, with LanceDB | [Agentic RAG with LanceDB](https://agno-v2.mintlify.site/knowledge/agents/agentic-rag-lancedb.md) |
| Let the model choose when to search, with PgVector | [Agentic RAG with PgVector](https://agno-v2.mintlify.site/knowledge/agents/agentic-rag-pgvector.md) |
| Retrieve before the first model call, with LanceDB | [Traditional RAG with LanceDB](https://agno-v2.mintlify.site/knowledge/agents/traditional-rag-lancedb.md) |
| Retrieve before the first model call, with PgVector | [Traditional RAG with PgVector](https://agno-v2.mintlify.site/knowledge/agents/traditional-rag-pgvector.md) |

## Developer Resources

* [Agent schema](https://agno-v2.mintlify.site/reference/agents/agent.md)
* [Knowledge schema](https://agno-v2.mintlify.site/reference/knowledge/knowledge.md)
* [Cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/07_knowledge/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.