> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/agents/guides/knowledge-base-setup.md).

# Setting up the knowledge base

Provision retrieval grounding: a managed collection on the platform, or your own HTTP search endpoint. Includes field/slot contracts and verification steps.

> **Context** — Assumes [Knowledge base & retrieval](https://docs.interactive.ai/agents/concepts/knowledge-base.md) (the two implementations and how a retrieval runs). This guide is the provisioning walkthrough for each, plus how to verify grounding actually works.
>
> YAML examples follow **manifest schema 1.4.0**. Manifest and content shapes are schema-versioned and differ across runtime versions — see [Versioning & compatibility](https://docs.interactive.ai/agents/operations/versioning.md).

## Choosing an implementation

Decide once per agent — `agent_config.search` holds exactly one:

* **`collections`** if your corpus lives in a managed collection on the platform. You define the search as a list of typed fields; the agent produces each field's text (and embeds the vector fields) and queries the collection — dense, keyword, or a hybrid of both.
* **`external`** if search already exists in your stack (Elasticsearch, a RAG service, a vendor API) or you need custom ranking. The agent sends conversation context; you return snippets.

## Option A: managed collections

### 1. Create the collection

Build a collection in a platform database and load your chunks (see the `iai collections` command reference). A collection can carry several vector slots and, optionally, a full-text index — the agent can query whichever of these you configured. Each vector slot has an embedding model bound to it at creation time — the manifest never re-declares that model.

### 2. Declare the search

The search is a list of **fields**. Each field names the prompt that turns the conversation into its text, and a `type`:

* **`str`** — the text is sent as a keyword query.
* **`vector`** — the agent embeds the text using the model bound to the target slot and matches it against that slot.

One field runs a single search; several fields run each as its own lane and fuse the results. A field searches the slot named by `name`, or by `slot` when you want several differently-prompted fields fused on one slot.

```yaml
agent_config:
  search:
    type: collections
    database: kb-prod
    collection: support_articles
    fields:
      - name: embedding                 # matches the collection slot
        type: vector
        llm_description: { id: semantic-query-rewrite, version: 3 }
      - name: broad                     # second lane fused on the same slot
        slot: embedding
        type: vector
        llm_description: { id: broad-topic-rewrite, version: 1 }
      - name: keywords
        type: str
        llm_description: { id: keyword-extract, version: 1 }
    limit: 5
    history_limit: 5
    filter: { kb_location: article }
```

Results reach the model with their full payload: every metadata key you stored on a chunk is rendered alongside its text, so a custom schema (prices, URLs, dates…) is usable context, not just the chunk body.

Authentication uses the agent's existing platform keys — no extra credentials, and the organization and project are resolved automatically at startup.

Startup describes the live collection and validates the declared fields against it — a `vector` field targeting a slot that doesn't exist, a slot with no bound embedding model, or a `str` field on a collection without full-text enabled all fail boot with an error naming the problem.

## Option B: external search endpoint

### 1. Implement the endpoint

One POST route; request and response contracts are fixed (full details in [Knowledge base & retrieval](https://docs.interactive.ai/agents/concepts/knowledge-base.md#type-external-bring-your-own-search)):

```python
from fastapi import FastAPI, Header, HTTPException
from pydantic import BaseModel

app = FastAPI()

SEARCH_API_KEY = "your-shared-secret"


class Message(BaseModel):
    role: str       # "customer" | "agent" | "tool"
    content: str


class SearchRequest(BaseModel):
    session_id: str
    agent_id: str
    top_k: int
    messages: list[Message]


@app.post("/agent-search")
async def agent_search(
    body: SearchRequest,
    authorization: str | None = Header(default=None),
) -> list[str]:
    if authorization != f"Bearer {SEARCH_API_KEY}":
        raise HTTPException(status_code=401)

    query = build_query(body.messages)          # your rewriting
    hits = run_search(query, limit=body.top_k)  # your engine
    return [hit.snippet for hit in hits]        # bare array of strings
```

Hard requirements: respond within the configured timeout (default 5s); return a **bare JSON array of strings**; treat `messages` as most-recent-last. Anything else — envelope objects, non-200s, slow responses — makes the retrieval soft-fail (the turn proceeds ungrounded).

### 2. Declare it

```yaml
agent_config:
  search:
    type: external
    url: https://search.internal.example.com/agent-search
    api_key: ${SEARCH_API_KEY}
    top_k: 5
    max_messages: 20
    timeout_seconds: 5.0
```

## Verifying grounding (both options)

1. **Boot check** — a slot/collection mismatch (`collections`) fails startup; read the error, it names the problem.
2. **Ask a question only the corpus can answer** ("what exactly happens if I cancel 12 hours before pickup?"). A grounded reply cites specifics from your documents; an ungrounded one generalises.
3. **Inspect the trace** — retrieval appears in the turn's trace with the query text and returned snippets; see [Observability](https://docs.interactive.ai/agents/guides/observability.md).
4. **Test the soft-fail** — take the KB down and confirm the agent still answers (from prompt + history) while logs show retrieval warnings. That's the designed behaviour; alert on the warning rate, not the turn failure (there isn't one). See [Troubleshooting](https://docs.interactive.ai/agents/operations/troubleshooting.md).

## Operational notes

* **Corpus hygiene beats `limit`/`top_k` tuning:** wrong-answer regressions are usually stale or contradictory documents. Raise the result count only when answers visibly miss available context — every extra snippet costs prompt space on every retrieval.
* **Fused searches:** `min_score` and `exact` interact with `fusion_k` and the number of fields — see the field table in [Knowledge base & retrieval](https://docs.interactive.ai/agents/concepts/knowledge-base.md#collections-fields) before tuning either.


---

# 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.interactive.ai/agents/guides/knowledge-base-setup.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.
