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

# Agents with Knowledge

> Understanding knowledge and how to use it with Agno agents

**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](/knowledge/overview) documentation.
</Note>

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**.
</Tip>

## 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.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 in 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.
</Tip>

## 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 ID of the knowledge content that this content is linked 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 offer the best solution for retrieving relevant results from dense information quickly.

### Adding contents

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

<Steps>
  <Step title="Parse the content">
    A reader is used to parse the content based on the type of content that is
    being inserted
  </Step>

  <Step title="Chunk the information">
    The content is broken down into smaller chunks to ensure our search query
    returns only relevant results.
  </Step>

  <Step title="Embed each chunk">
    The chunks are converted into embedding vectors and stored in a vector
    database.
  </Step>
</Steps>

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/08_knowledge/testing_resources/cv_1.pdf",
        metadata={"user_tag": "Engineering Candidates"},
    )
)
```

<Tip>
  See more details on [Loading the Knowledge
  Base](/knowledge/overview#loading-the-knowledge).
</Tip>

<Note>
  Knowledge filters are currently supported on the following knowledge base
  types: <b>PDF</b>, <b>PDF\_URL</b>, <b>Text</b>, <b>JSON</b>, and <b>DOCX</b>.
  For more details, see the [Knowledge Filters
  documentation](/knowledge/concepts/filters/overview).
</Note>

## Example: Agentic RAG Agent

Let's build a **RAG Agent** that answers questions from a PDF.

<Steps>
  <Step title="Set up the database">
    Let's use `Postgres` as both our 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:16
    ```

    <Note>
      This docker container contains a general purpose Postgres database with the `pgvector` extension installed.
    </Note>

    Install required packages:

    <CodeGroup>
      ```bash Mac theme={null}
      uv pip install -U pgvector pypdf psycopg sqlalchemy
      ```

      ```bash Windows theme={null}
      uv pip install -U pgvector pypdf psycopg sqlalchemy
      ```
    </CodeGroup>
  </Step>

  <Step title="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.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,
            )
        )
    ```
  </Step>

  <Step title="Run the agent">
    Run the agent

    ```python theme={null}
    python agentic_rag.py
    ```
  </Step>
</Steps>

## Developer Resources

* View the [Agent schema](/reference/agents/agent)
* View the [Knowledge schema](/reference/knowledge/knowledge)
* View [Cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/08_knowledge/)