> 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/concepts/knowledge-base.md).

# Knowledge base & retrieval

Retrieval grounding for the agent: managed collections on the platform, or an external HTTP search endpoint you own. Exactly one, selected by type.

> **Context** — Retrieval grounds the agent's answers in your documents (help-centre articles, product docs, policies-the-business-kind). It is optional: omit the `search` block entirely and the agent runs without retrieval. Setup walkthrough: [Setting up the knowledge base](https://docs.interactive.ai/agents/guides/knowledge-base-setup.md).
>
> 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).

## One slot, two implementations

`agent_config.search` is a single slot selected by a `type` tag — you get exactly one of:

| `type`        | What it is                                                                                                                                                                                                                | Choose when                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `collections` | The managed retriever: the agent queries a collection on the deployment-operator search API — dense (vector), full-text (keyword), or a hybrid fusion of both, driven by a list of typed fields you declare.              | Your corpus lives in a platform-managed collection and you want the agent to own rewriting and embedding. |
| `external`    | An HTTP endpoint **you own** receives the recent conversation and returns text snippets — the integration path for an existing search system, reached as a plain **HTTP call**. You own rewriting, embedding, and search. | You already run a search/RAG service, need custom ranking, or your corpus lives behind an API.            |

Either way the knowledge base is yours: a collection you provision on the platform, or an external HTTP search service you integrate. The agent only needs to reach the host/endpoint the manifest declares.

## `type: collections`: managed collections

```yaml
agent_config:
  search:
    type: collections
    database: kb-prod
    collection: support_articles
    fields:
      - name: embedding
        type: vector
        llm_description:
          id: semantic-query-rewrite
          version: 3
      - name: keywords
        type: str
        llm_description:
          id: keyword-extract
          version: 1
    limit: 5
    history_limit: 5
    filter:
      kb_location: article
```

### How a retrieval runs

1. **Produce each field's text** — one prompt call per field (on the `llms.search_query` model, which inherits `llms.default`) turns the last `history_limit` customer messages into that field's query text. The prompt named by `llm_description` supplies your domain instructions.
2. **Embed vector fields** — for `type: vector` fields, the agent embeds the produced text using the model bound to the target collection slot (see below) — never a model you declare in the manifest.
3. **Search** — a single field runs one lane; several fields run each as its own lane (dense, keyword, or mixed) and the agent fuses the ranked results (reciprocal rank fusion, `fusion_k`).
4. **Ground** — the top `limit` results, with their full stored metadata, are appended to the agent's context for the turn.

### Field types and slots

Each entry in `fields` is either:

* **`type: str`** — the produced text is sent as a full-text keyword query. Requires the collection to have full-text search enabled.
* **`type: vector`** — the agent embeds the produced text and matches it against a collection **vector slot**. The field's `name` names the slot unless `slot` overrides it — set `slot` when you want several differently-prompted fields fused onto the same slot.

The embedding model and dimension are **never declared in the manifest**: the agent reads both from the target slot's embedding binding (a describe call against the collection) at boot. A vector field always needs a slot with a bound embedding model — inspect a collection's slots with `iai databases describe`.

### Collections fields

| Field               | Type                       | Required | Default                             | Meaning                                                                                                                                                                                          |
| ------------------- | -------------------------- | -------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `database`          | string                     | yes      | —                                   | Operator database hosting the collection.                                                                                                                                                        |
| `collection`        | string                     | yes      | —                                   | Collection (table) to query.                                                                                                                                                                     |
| `operator_base_url` | string                     | no       | `https://deployment.interactive.ai` | Deployment-operator host. Override only for non-standard deployments.                                                                                                                            |
| `fields`            | list of field objects, ≥ 1 | yes      | —                                   | The query: one or more typed fields.                                                                                                                                                             |
| `limit`             | integer 1–100              | no       | `5`                                 | Results returned to the agent (final top-k).                                                                                                                                                     |
| `history_limit`     | integer ≥ 1                | no       | `5`                                 | Recent customer messages the per-field prompts see (most-recent last).                                                                                                                           |
| `filter`            | object                     | no       | `{}`                                | Static metadata filter, Mongo-style operators. Applied to every lane.                                                                                                                            |
| `fusion_k`          | integer ≥ 1                | no       | `60`                                | Reciprocal-rank-fusion constant. Used only when more than one field.                                                                                                                             |
| `min_score`         | float                      | no       | —                                   | Drop results scoring below this. For a single `vector` field, enforced platform-side on the slot's similarity scale; for fused searches, applied by the agent on the RRF scale (\~1/`fusion_k`). |
| `exact`             | boolean                    | no       | `false`                             | Brute-force exhaustive search, bypassing the approximate index. Only valid with a single `vector` field.                                                                                         |

Each entry in `fields`:

| Field             | Type                           | Required | Default | Meaning                                                                                                   |
| ----------------- | ------------------------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `name`            | string, unique across `fields` | yes      | —       | Field label. For `type: vector` it also names the collection slot to search unless `slot` says otherwise. |
| `type`            | `vector` \| `str`              | yes      | —       | `vector` → dense lane on a collection slot. `str` → full-text keyword lane.                               |
| `llm_description` | versioned ref                  | yes      | —       | Prompt whose output is this field's text for the turn.                                                    |
| `slot`            | string                         | no       | `name`  | Collection vector slot this field searches. Only valid for `type: vector`.                                |
| `candidate_limit` | integer 1–1000                 | no       | —       | Candidates this lane retrieves before fusion. No effect when the search is a single `vector` field.       |

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

### Boot validation

Startup describes the collection and checks the declared fields against it, failing boot with a specific error when:

* a `vector` field's slot doesn't exist on the collection,
* that slot has no bound embedding model,
* a `str` field is declared but the collection has full-text search disabled.

## `type: external`: bring your own search

```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
```

### Request your endpoint receives

```json
{
  "session_id": "sess_abc123",
  "agent_id": "agt_xyz789",
  "top_k": 5,
  "messages": [
    {"role": "customer", "content": "What's your cancellation policy?"},
    {"role": "agent", "content": "Free cancellation up to 24 hours before pickup."},
    {"role": "customer", "content": "And for one-way rentals?"}
  ]
}
```

`messages` is the last `max_messages` turns, most-recent **last**, with `role` normalised to `customer` | `agent` | `tool`. When `api_key` is set the request carries `Authorization: Bearer <resolved key>`.

### Response your endpoint must return

A bare JSON array of strings — each one a snippet to ground on:

```json
[
  "One-way rentals can be cancelled free of charge up to 24 hours before pickup; the 50 EUR one-way fee is fully refunded.",
  "Cancellations within 24 hours of pickup forfeit one day's rental rate."
]
```

Snippets are joined with `\n\n---\n\n` and appended to the agent's context as-is. Empty/whitespace-only strings are dropped. Any other shape (object envelope, non-string items, non-list root) is treated as a failure.

### External fields

| Field             | Type             | Required | Default | Meaning                                                                                                |
| ----------------- | ---------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `url`             | string           | yes      | —       | Full endpoint URL the runtime POSTs retrieval requests against. Scheme required; no query or fragment. |
| `api_key`         | `${VAR}` env-ref | no       | —       | Sent as `Authorization: Bearer`.                                                                       |
| `top_k`           | integer ≥ 1      | no       | `5`     | Forwarded in the envelope; your endpoint is expected to honour it.                                     |
| `max_messages`    | integer ≥ 1      | no       | `20`    | History cap per request.                                                                               |
| `timeout_seconds` | float > 0        | no       | `5.0`   | HTTP timeout.                                                                                          |

## Failure semantics: retrieval soft-fails

For both implementations, **retrieval failure never fails the turn**. Timeouts, connection errors, non-200 responses, malformed results — all log a warning and the turn proceeds with no retrieved context. The agent answers from the system prompt, policies, and history alone. Watch for retrieval warnings in logs if answers suddenly lose grounding — see [Troubleshooting](https://docs.interactive.ai/agents/operations/troubleshooting.md).

## See also

* [Setting up the knowledge base](https://docs.interactive.ai/agents/guides/knowledge-base-setup.md) — provisioning walkthrough
* [Models](https://docs.interactive.ai/agents/concepts/models.md) — where the rewrite and embedding calls fit
* [Conversation lifecycle](https://docs.interactive.ai/agents/concepts/conversation-lifecycle.md) — when retrieval happens in a turn


---

# 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/concepts/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.
