Skip to main content
Upgrading builds an agent knowledge base from a classic knowledge base and leaves the classic one as it is. Your apps keep answering from the classic knowledge base until you switch them over, so you can review and test the Agent Knowledge Base at your own pace. An agent knowledge base serves Workflow and Chatflow apps, the new Agent, the Service API, and the Dify CLI. Chatbot, legacy Agent, and Text Generator apps stay on the classic knowledge base. For what changes between the two, see the comparison.

​
What Carries Over

The upgrade brings your content into the agent knowledge base and indexes every document again there. Sections, summaries, and chunks are built fresh and won’t match the classic ones. These come across with it:
  • Documents: uploaded files are uploaded again, and Notion pages and crawled websites come in through sources the upgrade creates for them.
  • Metadata: the fields and every document’s labels, so you can set the same filters on the Agent Knowledge Retrieval node.
  • Retrieval settings: Top K, score threshold, and the embedding and rerank models. If either model is missing or no longer available, the workspace default takes its place.
  • Access: the Permissions setting, plus API access if it was on for the classic knowledge base. Workflow access starts on only if a published Workflow or Chatflow app used the classic knowledge base. A key created for All Knowledge Bases also reaches the agent knowledge base, while a scoped key doesn’t. Either way, your code has to call the agent knowledge base’s own API with its new ID.
  • Basics: the name, description, and tags.
The reasoning model and retrieval depth have no classic counterpart. The model starts as the workspace default, and depth starts at Fast. Changing the reasoning model later re-indexes every document, so for a large knowledge base, check that the workspace default is the one you want before you upgrade.

​
Upgrade to an Agent Knowledge Base

Before you start, check that:
  • You have edit permission on the classic knowledge base.
  • Your workspace has default system reasoning, embedding, and rerank models.
  • The classic one isn’t an external knowledge base or one built with a knowledge pipeline. Neither can be upgraded. Create an agent knowledge base and add their content instead.
  • Every uploaded file is 15 MB or smaller. A single larger file, or one in a format agent knowledge bases don’t accept, fails the whole upgrade. Split or replace such files in the classic knowledge base before you start.
  • For Notion pages, the same Notion workspace is connected in Integrations > Data Source. For crawled websites, the crawl provider they used is connected there too.
Upgrading indexes every document again and consumes tokens from the reasoning and embedding models, so for a large knowledge base, warn whoever watches model spend first. In Knowledge, open the classic knowledge base’s menu and start the upgrade. It runs in the background, and its progress shows under Agent. Expect minutes to hours depending on size.
The sources the upgrade creates are set to manual sync, so give each one a schedule if the content should keep refreshing.

​
Switch Your Apps

Before switching, review the indexed documents and test retrieval with the questions the app actually faces. If the agent knowledge base’s Workflow access is off, turn it on in its Settings first. Then, in your workflows:
  1. Add an Agent Knowledge Retrieval node that searches the agent knowledge base, connect it where the Knowledge Retrieval node was, set the same metadata filters on it, and point later nodes, such as the LLM’s Context, at its result.
  2. Run tests, remove the Knowledge Retrieval node once the app answers well from the agent knowledge base, and publish.
Delete the classic knowledge base only when no app uses it anymore, including the Chatbot, legacy Agent, and Text Generator apps that can’t be switched.
Last modified on October 28, 2026