> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/guides-and-quickstarts/agent-builder-and-skills/ground-an-agent-using-a-knowledge-base.md).

# Ground an agent using a knowledge base

Connect a knowledge base when an agent needs to answer questions from your documents. The agent searches those documents for relevant passages. Citations let readers open the source behind an answer.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FGP1X2aHjc7PRxoQzChNU%2FG012.mp4?alt=media&token=4e7e22ba-da81-4d0f-91fc-6f3d1caf2f3e>" %}

## Before you start

If you do not have a knowledge base yet, follow [Create a knowledge base](/guides-and-quickstarts/knowledge-and-retrieval/create-a-knowledge-base.md) to create one and upload your documents, then return here. You also need an agent; start with [Build your first AI agent](/guides-and-quickstarts/agent-builder-and-skills/build-your-first-ai-agent.md) if necessary.

Open the knowledge base and look for **Indexed** in the document status list. Indexing prepares the document for search; an uploaded file is not necessarily ready. Open a document’s **Parsed** view to inspect extracted text and **Chunks** to inspect the passages used for search. If a document shows an error or remains unavailable, use [Sync and ingestion lifecycle](/guides-and-quickstarts/knowledge-and-retrieval/sync-and-ingestion-lifecycle.md).

![Knowledge base parsed content before attachment](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/dBUXKegVeRkqNPgt1rqf/assets/g012-g012-01-source-preview.png)

## Connect the knowledge base

In Agent Builder, select **Add Knowledge Sources → Add Knowledge Base → Select existing Knowledge Base**. Choose the knowledge base. Enable **Use citations** if readers need source references.

![Attached knowledge base and citation option](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/8BgwFN5Mp0vcHswosyWa/assets/g012-g012-02-knowledge-attached.png)

## Explain when to search

In **Instructions**, state which questions require a knowledge search. Explain what the agent should do when the documents do not contain an answer. Adapt this pattern:

```
For questions about the documents attached to this agent, search the knowledge base.
Base the answer on the retrieved passages and include available source citations.
If the passages do not answer the question, say what information is missing.
```

![Agent instructions for knowledge searches](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/lDcKdiMStOWVVqbSnXo8/assets/g012-g012-03-instructions-v2.png)

## Review an answer and its source

Ask a question covered by the documents.

![Answer based on knowledge base documents](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/NP2sDbfvpcl1jwdDXX1s/assets/g012-g012-04-cited-answer.png)

Open the source indicator beneath the response. Compare the cited passage with the answer.

![Cited source passage for an answer](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/MAf3cfh5ckmmuXkKLx8z/assets/g012-g012-05-source-citation.png)

For a question outside the available information, the response should explain what is missing.

![Response when the documents lack an answer](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/YiYMLAR6qjegZ03yis2T/assets/g012-g012-06-missing-fact.png)

## Disconnect a knowledge base

Remove the knowledge source from the agent when it is no longer needed.

![Agent after knowledge source removal](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/YZfC3RbHX1fkbLVty0q4/assets/g012-g012-07-knowledge-removed.png)

## Important behavior

Removing the source from an agent does not delete the shared knowledge base.

A citation provides a way to inspect supporting information. Read the cited passage to check whether it supports the answer.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/guides-and-quickstarts/agent-builder-and-skills/ground-an-agent-using-a-knowledge-base.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.