Connect knowledge tools

Overview

Knowledge tools let your persona search uploaded documents and use retrieved passages in its answers through Retrieval-Augmented Generation (RAG). Instead of relying only on the LLM’s training data, your persona can access your organization’s specific documentation, policies, and knowledge base. Use this guide to connect your uploaded documents to a persona. Before selecting folders, check the knowledge scope for its audience. Every document in the selected folders should be appropriate for that persona.

Prerequisites

Before creating knowledge tools, you need:

Knowledge folders created (see Set up your knowledge base)
Documents uploaded and in READY status
Basic understanding of RAG concepts (see Knowledge overview)

Creating a knowledge tool

Knowledge tools are saved to your organization’s tool library, so one tool can be attached to several personas.

The quickest path

The first time you upload documents to a persona, Anam creates the knowledge tool for you. On the Prompt tab, open the Knowledge card and select Upload documents. Once the upload finishes, a tool named after the persona is created, pointed at the new folder, and attached to the persona draft. Select Publish before creating a session with this persona’s personaId — until you do, those sessions run with the persona’s previously published tools. See when you need to publish. You only need the steps below to control the tool’s name, its description, or which folders it searches.

Creating one yourself

Open the tool editor

Go to the Tools tab in Anam Lab and select Add tool.The menu offers Client tool and Server tool — there is no knowledge entry, so pick either one and change the type in the next step.

Set the type to Knowledge

In the editor, set Type to Knowledge, then fill in:

Name: search_product_docs (snake_case)
Instructions: when the persona should search — this is what the model reads to decide
Knowledge folders: select every folder this tool may search

Save and publish

Select Create tool, then Publish the persona.

The tool is saved to your tool library with a unique ID, and publishing makes it available to sessions created with this persona’s personaId.

Use in session

Create a session using the persona ID:

const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ANAM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    personaConfig: {
      personaId: "your-persona-id", // Published tools loaded automatically
    },
  }),
});

To create a tool through the API instead, see the knowledge tool configuration in the tools overview.

Write the instructions

When deciding whether to call a knowledge tool, the model sees the tool’s instructions but not its folders, filenames, or document contents. Write instructions that tell the model when to search. The field is labeled Instructions in the Lab and description in the API, and it holds up to 1024 characters. Name the subjects your folders actually cover, in the words a user would use, and say when not to search.

Don’t	Do
Describe the mechanism: “Searches the knowledge base.”	Describe the subjects: “Searches product documentation and billing FAQs.”
List document titles the user will never say.	List topics in the user’s words, such as refunds rather than `returns-policy-v4.pdf`.
Leave the boundary unstated.	Say what the folders do not cover, especially where another tool does.
Give two knowledge tools the same generic description.	Say what distinguishes each one; the model uses these descriptions to choose between them.

Example Don’t: “Search the knowledge base for relevant information.” Do: “Search product documentation and billing FAQs for questions about product features, installation steps, pricing tiers, invoices, and refunds. Do not use it for a customer’s own account details, such as their current balance or open tickets.” The first does not tell the model which questions match the tool. The second helps it recognize a billing question as something these folders can answer and a balance inquiry as something they cannot.

When the Lab creates a knowledge tool for you on first upload, it writes a generic description that names no subject. Replace it with one describing your own content, or the model is choosing when to search from a description that fits any knowledge base.

For naming conventions shared by all tool types, see Write clear descriptions. To tell the persona how to handle results and failures, see Tool calling definitions.

How many tools

Start with one tool covering the folders a persona needs, and split it only when the model has to choose between clearly different bodies of knowledge — product documentation versus billing policies, say. A separate tool per folder gives the model a sharper choice; a single tool over related folders keeps that choice simple. Group folders the same way you scoped them in the first place.

When you need to publish

Attaching a tool changes the persona, and persona changes are staged as a draft until you publish. Uploading documents does not change the persona draft, so it does not require publishing.

What you changed	Publish needed?
Attached a new knowledge tool	Yes — sessions created with `personaId` use the previously published tools until you publish
Changed which folders an existing tool searches	No — new sessions for every persona using that tool load the updated folders
Uploaded new or replacement documents	No — each document becomes searchable when it reaches `READY`
Deleted documents	No — deletion removes the document from search immediately

How knowledge tools work

When the AI needs information to answer a question, it uses a knowledge tool to search your documents.

User asks a question

User: “How do I authenticate API requests?”

AI decides to search

The AI determines the question requires information from your documentation and automatically formulates a search query.

The AI looks for the semantic meaning behind the user’s question, not just literal keywords.

System finds relevant content

The system searches the folders associated with the tool and retrieves the most relevant snippets from your documents.

AI generates a response

The AI uses the retrieved information to compose an answer.“To authenticate API requests, you’ll need to include your API key in the Authorization header like this: Authorization: Bearer <your API key>. You can get an API key from your dashboard.”

The user receives an answer grounded in your specific documentation.

Monitoring knowledge tool calls

Knowledge tool calls emit lifecycle events on the client that you can use for logging or analytics. Use toolType and toolSubtype to filter for knowledge-specific events:

import { AnamEvent } from "@anam-ai/js-sdk";

anamClient.addListener(AnamEvent.TOOL_CALL_STARTED, (event) => {
  if (event.toolType === "server" && event.toolSubtype === "knowledge") {
    console.log(`Knowledge search started: ${event.toolName}`);
  }
});

anamClient.addListener(AnamEvent.TOOL_CALL_COMPLETED, (event) => {
  if (event.toolType === "server" && event.toolSubtype === "knowledge") {
    console.log(`Knowledge search completed: ${event.toolName} in ${event.executionTime}ms`);
  }
});

anamClient.addListener(AnamEvent.TOOL_CALL_FAILED, (event) => {
  if (event.toolType === "server" && event.toolSubtype === "knowledge") {
    console.error(`Knowledge search failed: ${event.toolName} - ${event.errorMessage}`);
  }
});

See the Events SDK Reference for the full list of tool call event payloads and types.

Test the connection

Start a fresh session and ask a question that requires your uploaded reference material. Check that the intended knowledge tool runs, then follow Test your knowledge base to inspect passages and evaluate the answer, including exceptions and missing details. When replacing a folder, check every knowledge tool attached to the persona so that another tool does not retain access to the old material. See Replace an existing document.

Next steps

Set up your knowledge base

Create folders and upload documents

Client Tools

Trigger UI actions with client tools

Webhook Tools

Integrate external APIs

API Reference

Complete API documentation

Introduction

Personas

Avatar videos

Security & Compliance

Resources

Connect knowledge tools

Overview

Prerequisites

Creating a knowledge tool

The quickest path

Creating one yourself

Write the instructions

How many tools

When you need to publish

How knowledge tools work

Monitoring knowledge tool calls

Test the connection

Next steps

Set up your knowledge base

Client Tools

Webhook Tools

API Reference

​Overview

​Prerequisites

​Creating a knowledge tool

​The quickest path

​Creating one yourself

​Write the instructions

​How many tools

​When you need to publish

​How knowledge tools work

​Monitoring knowledge tool calls

​Test the connection

​Next steps

Set up your knowledge base

Client Tools

Webhook Tools

API Reference

Overview

Prerequisites

Creating a knowledge tool

The quickest path

Creating one yourself

Write the instructions

How many tools

When you need to publish

How knowledge tools work

Monitoring knowledge tool calls

Test the connection

Next steps