Create and manage knowledge bases for AI agents

A knowledge base is a named collection of PDF files from Celigo storage that your AI agents can search while they run. Attach knowledge bases to an AI agent so it can look up your policies, product documentation, contracts, and procedures when a record calls for it, without passing those documents in with every record. The agent bases its response on the passages it finds, each with the name of the file it came from.

This article is for builders who create AI agents and for administrators who control what those agents can read. It explains how knowledge bases work, how to create one and add files, how to attach knowledge bases to an agent, how to keep their content current, and how to see what an agent retrieved.

How knowledge bases work

A knowledge base references files in Celigo storage instead of copying them. When you link a file, Celigo indexes it in the background: it reads the file's text, splits it into passages, and makes the passages 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.

When an AI agent with attached knowledge bases runs, it gets one search tool for each knowledge base. Each tool is described to the agent by the knowledge base's name and description, plus a summary of the contents that Celigo generates as files are indexed. For each record, the agent decides whether to search, and which knowledge base to search, based on those descriptions and its 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, and uses them to respond.

Before each search runs, Celigo checks the knowledge base's content expiration setting, which can let the search proceed, proceed with a warning, or block it when the content is too old. 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, and its searches never reach another environment's knowledge bases.

When to use knowledge bases

• Decisions that follow a written policy. An agent that reviews expense reports checks each one against your expense policy. An agent that triages returns checks your returns policy.
• Answers from product or support documentation. An agent that drafts replies to support tickets looks up the relevant section of your product guides.
• Contract and procedure lookups. An agent that reviews orders checks contract terms or standard operating procedures, without you passing those documents in with every record.
• One source for many agents. Keep a set of documents in one knowledge base and attach it to every agent that needs it. When you update a file, every agent uses the new version.

Before you begin

• The multiple-environment structure. Knowledge bases use files in Celigo storage, which is available only to accounts on the multiple-environment structure. See Celigo storage overview.
• An API token with Full access. Requests that create and manage knowledge bases, link files, and attach knowledge bases to agents use an API token with Full access. Only account owners and administrators can create API tokens. See Create and manage API and Personal Access tokens.
• PDF files in Celigo storage. Knowledge bases index PDF files of up to 50 MB each.
• Create an AI agent.

Control who can see and change a knowledge base

Access to a knowledge base follows the integration it's registered to. Register each knowledge base to the integration whose AI agents use it by setting _integrationId when you create it. Users then get the same access to the knowledge base that they have to the integration: users with Manage access to the integration can change the knowledge base and its files, and users with Monitor access can view them. Users without access to the integration don't see the knowledge base.

• Account owner and administrators see and manage every knowledge base, including knowledge bases that aren't registered to an integration.
• An API token with Full access sees and manages every knowledge base in its environment.
• A knowledge base that isn't registered to an integration is visible only to the account owner and administrators.
• Anyone who can see a knowledge base sees all of its files, including files in Celigo storage folders they can't open. To link a file, you need access to it in Celigo storage.

Create a knowledge base and add files

Creating a knowledge base takes four steps: upload your PDFs to Celigo storage, create the knowledge base, link the files to it, and check that the files are indexed. The examples use the North America API address. In another region, use that region's address, such as https://api.eu.integrator.io. The Knowledge base API reference lists every region's address.

Step 1: Upload your PDFs to Celigo storage

1. Go to Resources > File storage.
2. Open the folder you want. If the knowledge base will be registered to an integration, open that integration's folder so that the same users can open the files.
3. Upload your PDF files, and wait for each upload to finish.

See Create folders and upload files in integrator.io. You can also upload files with the Celigo storage API.

Wait for each upload to finish before you link the file, and then find each file's ID. For example, search Celigo storage by name:

curl "https://api.integrator.io/v1/storage/items?search=returns" \
  -H "Authorization: Bearer <your API token>"

Each entry in items has the file's _id and name.

Step 2: Create the knowledge base

Send a POST request with the knowledge base's name, a description, and a content expiration setting:

curl -X POST "https://api.integrator.io/v1/knowledgebases" \
  -H "Authorization: Bearer <your API token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Returns policy",
    "description": "Return windows, eligibility rules, and refund methods for retail and wholesale orders. Use it to decide whether a return is eligible and how to refund it.",
    "contentExpiration": "never",
    "_integrationId": "683a1f2e9b0c4d001e8f7a23"
  }'

The response is the new knowledge base. Keep its _id:

{
  "_id": "6a1f0c2e9b0c4d001e8f7a01",
  "name": "Returns policy",
  "description": "Return windows, eligibility rules, and refund methods for retail and wholesale orders. Use it to decide whether a return is eligible and how to refund it.",
  "contentExpiration": "never",
  "_integrationId": "683a1f2e9b0c4d001e8f7a23",
  "createdAt": "2026-10-29T17:02:11.000Z",
  "lastModified": "2026-10-29T17:02:11.000Z"
}

Always send contentExpiration. Set it to never, or set it to warn or block and add a contentAge. A request that sends neither is refused, because the default is warn. See Keep knowledge base content current in this article.

Step 3: Link files to the knowledge base

Link each file with its Celigo storage _id and its file name:

curl -X POST "https://api.integrator.io/v1/knowledgebases/6a1f0c2e9b0c4d001e8f7a01/files/link" \
  -H "Authorization: Bearer <your API token>" \
  -H "Content-Type: application/json" \
  -d '{ "_fileId": "683b2a0e1c3d5f001a9e8b01", "filename": "returns-policy-2026.pdf" }'

A 202 Accepted response means indexing is queued. Its _id is the file's ID within the knowledge base, which you use to remove the file later, and it's also in the knowledge base's file list. Linking doesn't move or copy the file in Celigo storage.

Step 4: Check that the files are indexed

List the knowledge base's files to see each file's status:

curl "https://api.integrator.io/v1/knowledgebases/6a1f0c2e9b0c4d001e8f7a01/files" \
  -H "Authorization: Bearer <your API token>"

An agent can search a knowledge base as soon as at least one of its files is indexed. Files still being indexed are searchable once they finish.

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. Without one, the agent sees only a generic description with the knowledge base's ID and can't tell what it holds.
• Say what's in it 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.

Celigo adds a summary of the contents to the description the agent sees and updates it as files are indexed. The name and description you write still matter most, because the summary describes what's in the files, not when to use them.

Attach knowledge bases to an AI agent

An AI agent's knowledge bases are listed in its aiAgent.attachedKnowledgeBaseIds, which holds up to 50 knowledge base IDs. To attach knowledge bases, replace the list with every ID the agent should have:

curl -X PATCH "https://api.integrator.io/v1/imports/6a0e7f3c2d1b4a0012c4e9f2" \
  -H "Authorization: Bearer <your API token>" \
  -H "Content-Type: application/json" \
  -d '[{ "op": "replace", "path": "/aiAgent/attachedKnowledgeBaseIds", "value": ["6a1f0c2e9b0c4d001e8f7a01"] }]'

The response is 204 No Content. The agent can search the knowledge bases from its next run.

• To detach a knowledge base, replace the list without its ID. To detach all of them, send an empty list, []. Detaching never deletes the knowledge base.
• Every knowledge base you add is checked when you save. It must exist in the agent's environment, and your token must be able to see it.

Important: When you update an AI agent with PUT, include attachedKnowledgeBaseIds in the aiAgent object. A PUT that leaves it out can remove the agent's knowledge bases.

To try the agent before it runs in a flow, ask it a question with the Celigo CLI's ai-agents chat command:

celigo ai-agents chat 6a0e7f3c2d1b4a0012c4e9f2 --message "How many days do customers have to return unworn items?"

The response holds the agent's reply and a tools list, which names knowledge_retrieval__ followed by the ID of each knowledge base the agent searched. Each chat is a real, billed run of the agent.

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. The setting applies to the whole knowledge base.

• contentExpiration -- What happens when the knowledge base's content is older than contentAge. Default: warn. Accepted values: never, warn, block.
• never: Content never expires, and contentAge is ignored.
• warn: The agent searches as usual, and its execution log records a content-age warning.
• block: The agent gets no passages and is told the knowledge base isn't available. Its execution log records the block. The run continues without that knowledge base.
• contentAge -- How old the content can get, as a value from 1 to 10,000 and a unit of days, weeks, or months. A month is 30 days. Required when contentExpiration is warn or block.

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. Linking 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.

To change the setting, send only the fields you're changing:

curl -X PATCH "https://api.integrator.io/v1/knowledgebases/6a1f0c2e9b0c4d001e8f7a01" \
  -H "Authorization: Bearer <your API token>" \
  -H "Content-Type: application/json" \
  -d '{ "contentExpiration": "block", "contentAge": { "value": 12, "unit": "months" } }'

A change applies to every agent that uses the knowledge base, at its next search.

See what an agent retrieved

Each knowledge base search appears in the AI agent's execution logs as a tool call. The tool's name is knowledge_retrieval__ followed by the knowledge base's ID. With basic logging, the tool call shows the search's decision:

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, along with the tool's input and output, as for any tool call at that level. See Monitor AI agent and guardrail activity with execution logs.

Check a knowledge base's health

A knowledge base's health shows whether its files are indexed and whether its content is past its content age:

curl "https://api.integrator.io/v1/knowledgebases/6a1f0c2e9b0c4d001e8f7a01/health" \
  -H "Authorization: Bearer <your API token>"

• availabilityState is Processing while any file is being indexed, Current when every file is indexed, Limited when some files are indexed and some failed, and Error when every file failed.
• needsAttention is true when reasons lists anything: fileFailed when a file failed to index, contentExpired when content is past its age and expiration is warn, and contentBlocked when content is past its age and expiration is block.
• contentExpiresAt is when the content will pass its content age, unless it changes first.

Update, remove, and delete

• Update a document: upload the new version to the same Celigo storage folder with the same name and select Replace, or replace the file with the Celigo storage API. Every knowledge base that uses the file indexes the new version, and the file stays linked to each one.
• Fix a file that failed: replace it in Celigo storage with a corrected PDF, or remove it from the knowledge base and link a corrected copy.
• Remove a file from a knowledge base: send DELETE /v1/knowledgebases/{_id}/files/{_kbFileId} with the file's ID within the knowledge base. The file stays in Celigo storage.
• Delete a knowledge base: detach it from every AI agent first. Otherwise the request is refused with a list of the agents that use it. Deleting a knowledge base removes its index and can't be undone. Its files stay in Celigo storage.

Clone agents and move them between environments

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.

Limits

Troubleshoot knowledge bases

• The agent never searches a knowledge base. Check that the knowledge base is in the agent's attachedKnowledgeBaseIds. 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 KnowledgeBaseNotReady. No file is indexed yet. Check each file's status. If every file failed, replace or relink corrected PDFs.
• The decision is ContentOutdatedBlocked. The content is older than the knowledge base allows. Replace the out-of-date files with current versions, or change contentAge or contentExpiration.
• Linking a file returns 404 storage_file_not_found. The file ID is wrong, the upload hasn't finished, or your token can't open the file. Wait for the upload to complete and check the ID.
• Linking a file returns 413 or 415. The file is larger than 50 MB or isn't a PDF. Convert or split it, upload it again, and link the new file.
• Saving an agent returns 422 attached_knowledge_base_invalid. A knowledge base you added doesn't exist in the agent's environment, or your token can't see it.
• Saving an agent returns 503 knowledge_base_validation_unavailable. Celigo couldn't verify the knowledge bases, and nothing was saved. Try again.
• Deleting a knowledge base returns 409 knowledge_base_in_use. Detach it from the agents named in the message, and then delete it.

Frequently asked questions

Does an agent search every attached knowledge base for every record? No. For each record, the agent decides whether a search would help, and which knowledge base to search, from each knowledge base's name, description, and summary and from its own instructions.

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 a knowledge base copy my files? No. It references files in Celigo storage, so each file counts toward your storage allowance once, however many knowledge bases use it.

Can I add Word documents, spreadsheets, or text files? Knowledge bases index PDF files. Convert other documents to PDF before you link them.

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.

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. For more information, see Track your AI agent actions and credits usage.

Can an agent use a knowledge base from another environment? No. An agent can attach only knowledge bases from its own environment.

Related articles

• Knowledge base API reference
• Learn about Celigo AI agents
• Create an AI agent
• Monitor AI agent and guardrail activity with execution logs
• Celigo Storage overview
• Create folders and upload files in integrator.io
• Create and manage API and Personal Access tokens