A knowledge base is a named collection of PDF files from Celigo Storage that your AI agents can search while they run. You create knowledge bases under AI studio > Knowledge bases, add files to them, and attach them to an AI agent in the agent's settings. The agent can then look up your policies, product documentation, contracts, and procedures when a record calls for it, and base its response on the passages it finds.
This article is for builders who create AI agents and for administrators who control what those agents can read.
Understand knowledge bases
A knowledge base references files in Celigo Storage instead of copying them. When you add a file, Celigo indexes it in the background so its text is searchable. A file counts toward your storage allowance once, however many knowledge bases use it, and one knowledge base can serve any number of AI agents. For example, an agent that reviews expense reports can check each report against your expense policy, and every agent that needs the policy can use the same knowledge base.
An AI agent with attached knowledge bases gets one search tool for each. The agent decides for each record whether to search, and which knowledge base to search, from the knowledge base's name and description, a summary of its contents that Celigo keeps up to date, and the agent's instructions. It doesn't search every knowledge base for every record. When it searches, it receives the most relevant passages, each with the name of its source file. Before each search, Celigo checks the knowledge base's content expiration setting, and every search and its outcome is recorded in the agent's execution logs.
Knowledge bases belong to an environment. An agent can attach only knowledge bases from its own environment.
Before you begin
- Celigo Storage. Knowledge bases use files in Celigo Storage, which is available only to accounts on the multi-environment structure. Knowledge bases appears under AI studio in accounts that have AI agents and Celigo Storage. See Celigo Storage overview.
- Manage access to an integration. To create a knowledge base, you need Manage access to an integration to register it to.
- PDF files. Knowledge bases index PDF files only. See Limits.
Control who can see and change a knowledge base
Access to a knowledge base follows the integrations it's registered to. Users get the same access to the knowledge base that they have to those integrations:
- Manage access to any of its integrations lets you edit the knowledge base, add and remove its files, change where it's registered, and delete it.
- Monitor access lets you view the knowledge base and its files. In the Knowledge bases list, the action reads View instead of Edit. Users with Monitor all access see every knowledge base that is registered to an integration, read-only.
- No access to any of its integrations means you don't see the knowledge base.
- Manage all access lets you create, edit, and delete knowledge bases, but each knowledge base you create must be registered to an integration.
- The account owner and administrators see and manage every knowledge base, and are the only users who can create or keep one that isn't registered to an integration.
- Files. Anyone who can see a knowledge base sees all of its files, including files in Celigo Storage folders they can't open. To add a file, you need access to it in Celigo Storage.
When you attach a knowledge base to an AI agent in an integration, the knowledge base is registered to that integration, the way a connection is.
Create a knowledge base
- Go to AI studio
, and then select Knowledge bases.
- Select + Create knowledge base.
- Under General, set the following:
- Name — Required. Unique within the environment, ignoring case.
- Description — What the knowledge base holds and when an agent should search it. Optional, but without one the agent sees only a generic description and can't tell what the knowledge base holds. See Describe a knowledge base so the agent uses it well.
-
Content expiration — Required. What happens when the content is older than Content age: Never expire (the default), Warn, or Block. See Keep knowledge base content current.
Content age — How old the content can get, in Days, Weeks, or Months. A month is 30 days. Required when Content expiration is Warn or Block.
- Under Option, select Create new integration and enter a name for the integration, or select Add to existing integrations and pick the integrations in Select integrations. Create new integration appears only if you can create integrations. The account owner and administrators can skip this step to keep the knowledge base outside an integration. On an existing knowledge base, add or remove integrations here and save.
- Select Next to save the knowledge base and open Files, and then select its PDF files. See Add files to a knowledge base.
The knowledge base appears in the Knowledge bases list when you select Next. When you save the files, Celigo starts indexing them, and the knowledge base's Status shows In progress until indexing finishes. An agent can search the knowledge base as soon as one of its files is indexed.
Knowledge bases screen
Go to AI studio , and then select Knowledge bases. The screen lists every knowledge base you can see. Use the search box to find one by name, and select Create knowledge base to add one.
| Column | What it shows |
|---|---|
| Name | The knowledge base's name. Select it to open the knowledge base. |
| Status | Whether agents can use the knowledge base. See Check a knowledge base's status. |
| Files | How many files the knowledge base has. Select the number to open Files. A dash means no files. |
| Last updated | When the knowledge base or its files last changed. |
| Expires | When the content passes its Content age, unless a file changes first. A dash means the content never expires, or no file is indexed. |
| Actions | The actions performed for each knowledge base. |
Select Actions on a row to see its actions:
| Action | What it does |
|---|---|
| Edit | Opens the knowledge base to change its settings, integrations, and files. Reads View if you can't change the knowledge base. |
| View audit log | Shows who changed the knowledge base and when. See Review a knowledge base's changes. |
| Used by | Lists the AI agents that use the knowledge base. |
| Delete | Deletes the knowledge base. See Update documents and delete knowledge bases. |
On the Knowledge bases tab of an integration, the actions also include Deregister, which sits between Used by and Delete. See Manage knowledge bases from an integration.
Manage knowledge base files
Add files to a knowledge base
Files shows your Celigo Storage folders. A selected file is in the knowledge base, and a file that isn't selected isn't.
- In the Knowledge bases list, select the knowledge base's name. Files opens.
- Open the folder that holds your files, or search for them, and select each file you want. The list shows folders and PDF files of 50 MB or less.
To add a file that isn't in Celigo Storage, open the folder where it should be stored, select Upload file, and select or drop a PDF file. Then select it in the list. Upload file appears only in folders you can upload to. Upload a knowledge base's files to the folder of an integration it's registered to, so that the same users can open them. See Create folders and upload files in integrator.io.
The files are added when you save, and indexing starts then. If a file can't be added, the message below the file list gives the reason, and the knowledge base's other changes are saved. Fix the problem, and save again. Save & close saves and closes Files, and Save keeps it open.
Files lists folders and PDF files of 50 MB or less and nothing else. Folder rows have a selection box.
Remove files from a knowledge base
Open the knowledge base, and clear each file you want to take out.
When you save, agents stop retrieving the file. Removing a file from a knowledge base never deletes it from Celigo Storage. If you remove a file you can't open in Celigo Storage, you can't add it back; someone who can open it has to.
Check each file's status
On Files, Status shows where each file in the knowledge base is. Folders, and files that aren't in the knowledge base, show a dash. Files refreshes on its own while any file is In progress.
- In progress — The file is waiting to be indexed, or Celigo is indexing it. Agents can't search it until it's indexed.
- Ready — The file is indexed, and agents can search it.
- Failed — The file couldn't be indexed. Hover over the status to see why and what to do.
| Why the file failed | What to do |
|---|---|
| Celigo couldn't read the PDF, usually because it's damaged. | Replace it in Celigo Storage with a corrected copy. |
| The file is larger than 50 MB, for example after a new version replaced it in Celigo Storage. | Split it into smaller PDFs, and add those. |
| The file isn't a PDF. | Convert it to PDF, and add it again. |
| The file is no longer in Celigo Storage. | Remove it, or restore it and add it again. |
| Celigo couldn't index the file for another reason. | Remove it and add it again. If it keeps failing, contact Celigo Support. |
Manage knowledge bases from an integration
The Knowledge bases tab of an integration lists only the knowledge bases registered to that integration. It has the same search box, columns, and row actions as the Knowledge bases screen, plus Deregister in each row's Actions, and Create knowledge base and Register existing above the list.
To register existing knowledge bases to an integration:
- Open the integration, and then select Knowledge bases.
- Select Register existing.
-
In Existing knowledge bases, which lists the knowledge bases that aren't registered to this integration, select one or more, and then select Register.
The other actions are:
- + Create knowledge base creates a knowledge base that is registered to this integration.
- Deregister asks you to confirm, and then removes the knowledge base from this integration only. Its other integrations keep it, and so does AI studio > Knowledge bases. Deregistering is refused while an AI agent or guardrail used by a step in this integration has the knowledge base attached.
- Delete removes the knowledge base from every integration it belongs to and deletes its index. See Update documents and delete knowledge bases.
Users with Monitor access to the integration see neither Register existing nor Deregister.
Use knowledge bases with AI agents
Attach knowledge bases to an AI agent
You need Manage access to the agent. With Monitor access, Select knowledge base is read-only.
- Open the AI agent.
- In General, open Select knowledge base, select each knowledge base the agent should search, and save the agent. You can search the list by name.
The agent can search the knowledge bases from its next run. To create a knowledge base without leaving the agent, select Create knowledge base at the bottom of the list, fill in the details, and save. The new knowledge base is selected for the agent and registered to the agent's integration. To detach a knowledge base, remove it from Select knowledge base, and save the agent. Detaching never deletes the knowledge base. Knowledge bases attached with the API appear in Select knowledge base, and saving the agent or switching its model keeps them attached.
Describe a knowledge base so the agent uses it well
An AI agent decides whether to search a knowledge base from its name and description, so write them for the agent:
- Always add a description that says what's in the knowledge base and when to use it. "Return windows, eligibility rules, and refund methods for retail and wholesale orders. Use it to decide whether a return is eligible" helps the agent more than "Policies."
- Keep each knowledge base to one subject. Separate knowledge bases for the returns policy and the shipping policy are easier for the agent to choose between than one that holds both.
- Mention the knowledge base in the agent's instructions, for example: "Use the Returns policy knowledge base to decide whether each return is eligible." If an answer must come from a knowledge base, also say what the agent should do when it finds nothing relevant.
Test an agent that uses knowledge bases
Before an agent runs in a flow, test it in Preview: ask questions that your documents answer, and then one that they don't, and check that the agent follows your instructions for that case. To see which knowledge bases the agent searched, select Show details under a response. See Preview an AI agent.knowledge_retrieval__ followed by the knowledge base's ID (Tyler checked the chat stream that Preview uses on 2026-10-27).
Monitor knowledge base status and content
Check a knowledge base's status
The Status column on the Knowledge bases screen updates on its own while indexing runs.
| Status | What it means | What agents get |
|---|---|---|
| In progress | Celigo is indexing one or more of the files. | The files already indexed, if any. |
| Ready | Every file is indexed. | All of the content. |
| Ready, in yellow, with a warning icon | Some files couldn't be indexed. See Check each file's status. | The files that were indexed. |
| Failed | No file could be indexed. | Nothing. |
| Expired | The content is older than Content age, and Content expiration is Block. | Nothing. |
| A dash | The knowledge base has no files. | Nothing. |
Hover over a status that needs attention to see why. The message names the files that failed, or says the content is past its age under Warn or Block. To fix expired content, replace the out-of-date files with current versions, or change Content age or Content expiration.
Keep knowledge base content current
Content expiration lets a knowledge base warn about or block content that's older than you allow, so an agent doesn't answer from a policy that's out of date. It applies to the whole knowledge base and to every agent that uses it, at its next search.
- Never expire — The default. Agents search the knowledge base whatever its age.
- Warn — When the content is older than Content age, agents still search it, and each search's execution log records a content-age warning. The Status in the list doesn't change; hover over it to see the reason.Warn (the list decision says an icon and a hover; the build shows the icon only on a yellow Ready).
- Block — When the content is older than Content age, agents get no passages and are told the knowledge base isn't available. The run continues without it. The list shows the knowledge base as Expired.
A knowledge base's content age is the time since its content last changed, which is the last time a file with new content finished indexing. Adding a file, or replacing a file with a changed version, resets the age once the file is indexed. Replacing a file with an identical copy doesn't. Removing a file never makes a knowledge base newer.
Monitor agent activity
See what an agent retrieved
Each knowledge base search appears in the AI agent's execution logs as a tool call named knowledge_retrieval__ followed by the knowledge base's ID. With basic logging, the tool call shows the search's decision:
| Decision | What happened |
|---|---|
Allowed |
The agent searched the knowledge base and received passages. |
AllowedWithWarningContentOutdated |
The content is older than its content age and expiration is Warn. The agent searched anyway. |
ContentOutdatedBlocked |
The content is older than its content age and expiration is Block. The agent got no passages. |
KnowledgeBaseNotReady |
No file in the knowledge base is indexed, because indexing is still running, every file failed, or the knowledge base has no files. The agent got no passages. |
With detailed logging, the tool call also shows the setting that applied, the reason a search was refused, the content's age, and the number of passages returned. See Monitor AI agent and guardrail activity with execution logs.
Review a knowledge base's changes
To see who changed a knowledge base and when, select Actions > View audit log. Knowledge base entries also appear in the account's audit log. See View or download your audit logs.
Update documents and delete knowledge bases
-
Update a document: go to Resources
, and then select File storage. Upload the new version to the same folder with the same name, and select Replace. Every knowledge base that uses the file indexes the new version, and the file stays in each one.
- Delete a file in Celigo Storage: it's removed from every knowledge base that uses it. If you restore the file from the recycle bin, add it to the knowledge base again.
-
Delete a knowledge base: select Actions
> Delete, and confirm. If an AI agent still uses the knowledge base, it isn't deleted, and the message names the agents. Detach it from them first. Deleting a knowledge base removes it from every integration, deletes its index, and can't be undone. Its files stay in Celigo Storage.
Move and automate knowledge bases
Knowledge bases don't travel with the agents that use them:
- A clone in the same environment keeps the source agent's knowledge bases.
- A clone into another environment, or an installed template or integration app, starts with no knowledge bases. Attach knowledge bases from the target environment.
- Pulling changes between environments keeps the target agent's own knowledge bases.
To manage knowledge bases, add files to them, and attach them to AI agents with the API, use an API token with Full access or a personal access token. A personal access token acts with its user's access. For example, a flow can upload a new version of a document to Celigo Storage, and every knowledge base that uses the file indexes it. See Knowledge base API reference.
Limits
| Item | Limit |
|---|---|
| File type | |
| File size | 50 MB per file |
| Knowledge bases per AI agent | 50 |
| Knowledge base name | 100 characters. Unique within an environment, ignoring case. |
| Knowledge base description | 2,000 characters |
| Content age | 1 to 10,000 days, weeks, or months |
Troubleshoot knowledge bases
- Saving a new knowledge base shows "Select an integration, or create one, before saving this knowledge base." Under Option, select Add to existing integrations and pick an integration you have Manage access to, or select Create new integration. Only the account owner and administrators can keep a knowledge base outside an integration.
- Saving shows "The knowledge base was saved, but some integrations could not be registered." The knowledge base and its other changes were saved. Register it to the remaining integrations under Option, or from each integration's Knowledge bases tab. You need Manage access to an integration to register a knowledge base to it.
- Deregister shows "The knowledge base is attached to an AI agent or guardrail used by a step in this integration. Detach it from all steps before deregistering." An AI agent or guardrail used by a step in the integration still has the knowledge base attached. Detach the knowledge base from each of them, and then deregister it.
- A file doesn't appear on Files, or Upload file isn't shown. The file isn't a PDF, it's larger than 50 MB, you can't open it in Celigo Storage, or its upload hasn't finished. Upload file appears only in folders you can upload to, so open a folder you can upload to, such as the folder of an integration you manage. Only the account owner and administrators can add items at the Celigo Storage root. Uploading shows "Only PDF files can be added to a knowledge base." or "PDF files must be 50 MB or smaller." for a file that isn't a PDF or is too large.
- Select knowledge base doesn't appear in the agent. Reload the agent: Select knowledge base is hidden while the list of knowledge bases can't be loaded. It also appears only in accounts that have AI agents and Celigo Storage.
- Select knowledge base shows "This knowledge base no longer exists. Detach it to remove it from this agent. Saving still works." An attached knowledge base was deleted. Remove it from Select knowledge base, and save the agent.
- The agent never searches a knowledge base. Check that it's selected in Select knowledge base. Then make its description say what's in it and when to use it, and mention it in the agent's instructions.
-
The decision is
KnowledgeBaseNotReadyorContentOutdatedBlocked. ForKnowledgeBaseNotReady, no file is indexed: wait if the knowledge base shows In progress, open it to see why each file failed if it shows Failed, or add files if it has none. ForContentOutdatedBlocked, replace the out-of-date files with current versions, or change Content age or Content expiration. - Saving an agent fails because Celigo couldn't verify its knowledge bases. Nothing was saved. Try again.
Frequently asked questions
How is a knowledge base different from an agent's instructions and tools? Instructions tell the agent what to do and how to make decisions. Tools let the agent perform actions in other systems. A knowledge base provides reference information that the agent can search when needed. Use instructions for rules and decision-making, tools for actions, and knowledge bases for reference documents such as policies, product guides, and procedures.
Does indexing a knowledge base consume AI credits? No. Indexing files in a knowledge base doesn't consume AI credits. However, content retrieved from a knowledge base becomes part of the agent's prompt and contributes to its token usage. A flow that writes files to Celigo Storage for a knowledge base is counted like any other flow. See Track your AI agent actions and credits usage. Tyler Lamparter decides whether to add it here.
What happens when a knowledge base is unavailable during a run? The agent is told the knowledge base isn't available and continues without its passages. The run doesn't fail. If an answer must come from the knowledge base, say in the agent's instructions what the agent should return when it can't search.
Which models process my documents? Celigo indexes your files and ranks search results with models that Celigo manages, whichever model your AI agent uses. The passages an agent retrieves are sent to the agent's own model as part of its prompt, like any other input.
Related articles
- Knowledge base API reference
- Learn about Celigo AI agents
- Create an AI agent
- Preview an AI agent
- Monitor AI agent and guardrail activity with execution logs
- View or download your audit logs
- Celigo Storage overview
- Create folders and upload files in integrator.io
- Track your AI agent actions and credits usage