---
title: Give agents reference documents
description: Create a knowledgebase and link it to an agent or judge.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

When an agent or judge needs the same reference material on every run, such as a policy, a product guide, or a scoring rubric, put it in a [knowledgebase](/platform/concepts/knowledgebase) and link it. You maintain the documents in one place, and every linked agent and judge reads the current version.

By the end you'll have a knowledgebase with at least one document, linked to the agents and judges that need it.

## Before you start

- You have the **Full access** role on the account. Read-only users still see **New knowledgebase**, **New document**, and the link buttons, but Prefactor refuses the change with an error.
- The agents or judges you want to link are registered. See [Register an agent](/guides/register-an-agent).
- You have the reference material to hand as Markdown, plain text, JSON, YAML, or CSV.

## Create the knowledgebase

1. Go to **Knowledgebases** and select **New knowledgebase**.

   The **New knowledgebase** dialog opens.

2. Enter a **Name** and a **Description**, then select **Create knowledgebase**.

   The name must be unique in the account. Write the description for the agent: it becomes part of the tool descriptions agents see, so say what the documents cover and when to use them. Prefactor confirms with "Knowledgebase created" and the new knowledgebase appears in the list.

3. Select the knowledgebase's name on its card.

   The [Knowledgebase page](/web-app/knowledgebase) opens, with **Connected agents and judges** and an empty **Documents** list.

## Add documents

4. Select **New document**.

   The **New document** dialog opens.

   ![The New document dialog with a path and some Markdown content entered, and Type set to Markdown.](../../../assets/screenshots/guides/new-document-dialog.png)

5. Enter a **Path**, such as `policies/refunds.md`.

   Slashes in the path put the document in a folder. **Type** follows the file extension, so `.md` picks **Markdown**; change it if the extension doesn't match the content.

6. Paste or write the document under **Content**, then select **Create document**.

   For Markdown, switch to **Preview** to check how it renders. Prefactor confirms with "Document created" and opens the new document's page. Go back to the knowledgebase and repeat steps 4 to 6 for each document.

## Link agents and judges

7. On the Knowledgebase page, select **Link agent or judge** in **Connected agents and judges**.

   The **Link an agent or judge** dialog opens.

8. Choose from **Agent or judge** and select **Link**.

   Each option shows its name and whether it's an agent or a judge. Prefactor confirms with "Agent linked" or "Judge linked", and it's listed under **Connected agents and judges**. Repeat for each agent or judge that needs the documents.

You can also link from the other side: on the agent's or judge's [Overview tab](/web-app/agent/overview), select **Link knowledgebase** in the **Knowledgebases** box, choose a **Knowledgebase**, and select **Link knowledgebase**.

## Verify

Open the agent's or judge's Overview tab. The knowledgebase is listed in the **Knowledgebases** box, which shows what that agent or judge can read. Hosted judges read their linked knowledgebases with built-in tools on every run, starting with the next run after you link. A hosted agent version gets the same tools only when its hosted configuration enables the `knowledgebases` tool.

## If it didn't work

- **Prefactor shows an error when you create or link.** Your role is Read only. Ask a Full access user to make the change.
- **Create knowledgebase fails on the name.** Another knowledgebase in the account already uses it. Choose a different name.
- **Link agent or judge can't be selected.** The note under the button says why: every agent and judge is already linked, or none are registered.
- **Link agent or judge is missing.** The knowledgebase is archived. Archived knowledgebases can't be linked; unarchive it from the **⋮** menu on its Knowledgebase page.
- **Link knowledgebase on the agent's side can't be selected.** The menu says why: no knowledgebases exist, none are active, or all of them are already linked. **Go to knowledgebases** takes you to create or unarchive one.
- **A document can't be edited.** The document or its knowledgebase is archived and read-only until you unarchive it.

## Other ways to do this

To manage knowledgebases from a script, create one with [POST /api/v1/knowledgebase](/api/platform/operations/actionknowledgebasecreate), add documents with [POST /api/v1/knowledgebase_document](/api/platform/operations/actionknowledgebasedocumentcreate), and link it with [POST /api/v1/agent_knowledgebase_link](/api/platform/operations/actionagentknowledgebaselinkcreate).

## Related

- [Knowledgebase](/platform/concepts/knowledgebase) — what a knowledgebase is and how agents read it.
- [Knowledgebases page](/web-app/knowledgebases) — every knowledgebase in the account.
- [Knowledgebase page](/web-app/knowledgebase) — documents, revisions, archiving, and connected agents and judges.
- [Agent page › Overview tab](/web-app/agent/overview) — the **Knowledgebases** box on an agent.
- [Evals](/platform/evals) — how judges score runs, including with reference material.