> ## Documentation Index
> Fetch the complete documentation index at: https://watermelon.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrate from a legacy Agent to a new Agent
If your AI Agent still uses **Domain Knowledge**, you are using Watermelon’s legacy Agent setup. Agent Settings and Instructions now have equal priority, Instructions are shorter, and Sources benefit from the newer retrieval/crawling architecture.
**Availability:** This guide applies to all plans if your Agent still uses **Domain Knowledge**. Whether you have a legacy Agent depends on when and how your Agent was created, not on your current plan.
## Does this guide apply to me?
Whether you have a legacy Agent depends on the type and age of your Agent, rather than your current Watermelon plan. New Agents created from **December 1, 2025** use Agent Settings instead of Domain Knowledge.
You can quickly check this by opening your Agent:
* Open your Agent.
* See **Domain Knowledge** → follow this guide.
* See **Agent Settings** → no migration needed.
Migrating is **not required**, but we strongly recommend it. We see better results with the new Agent setup, especially when prompts are structured correctly and Sources are re-crawled.
This migration is about improving your **Agent architecture**. It is separate from changing your AI model. Looking to change your AI model instead? See [Migrate your AI model.](https://watermelon.ai/docs/untitled-page-3)
## Why migrate to a new Agent?
The new Agent architecture works with **AI Engine 2.0**, which includes improvements to search, knowledge retrieval, web crawling, tool selection and overall performance.
But the biggest difference when migrating your configuration is how information and instructions are structured.
In a legacy Agent, Domain Knowledge has a higher priority than Instructions. Watermelon describes Domain Knowledge as the most important information layer in this setup, overriding other added knowledge.
In the new Agent, **Agent Settings and Instructions have the same priority**. This makes it easier for the Agent to consistently combine its general behaviour with instructions for specific situations, as long as the information does not contradict itself.
For example:
**Legacy setup:** Domain Knowledge says “Always answer formally,” while an Instruction says “Use an informal tone for sales questions.” Because Domain Knowledge has higher priority, the Instruction may not behave as expected.
**New setup:** Put the general tone in Personality and use a separate Instruction only when a specific scenario genuinely needs different behaviour.
You should use the migration to restructure and simplify your prompts.
**Do not disconnect your live channels yet.** Create and test the new Agent first. Only move your channels after you are satisfied with its responses.
### 1. Move Domain Knowledge to Agent Settings
**Legacy Agent:** four Domain Knowledge fields of up to 4,000 characters each
**New Agent:** three Agent Settings of up to 2,000 characters each
That means you should not try to copy everything over. The goal is to **restructure and simplify** the information.
Use the three Agent Settings like this:
### Personality
Use Personality mainly for **how the Agent should communicate**.
Think about:
* Tone of voice
* Formal or informal language
* Writing style
* How the Agent addresses customers
* The role or character of the Agent
Keep operational rules and detailed company information out of this field where possible.
### Your company
Use Your company for the most important information about your business.
This can include:
* What your company does
* Products or services
* Important business context
* Processes or flows the Agent should understand
* General rules that apply across many conversations
This field can also be useful for **important flows that are relevant throughout the Agent**, especially when they do not fit into one short Instruction.
### Guardrails
Use Guardrails for the things your Agent **cannot or should not do**.
For example:
* Topics the Agent should not answer
* Information it must never share
* Actions it is not allowed to perform
* Claims or promises it should not make
* Situations where it should hand over instead of answering
A simple way to think about the migration is:
**Personality = how should the Agent communicate?**
**Your company = what should the Agent know and understand about your business and processes?**
**Guardrails = what is the Agent not allowed to do?**
After restructuring these three fields, move more specific scenario-based behaviour into separate Instructions.
### 2. Rewrite your Instructions
**Important:** Legacy Agents had unlimited Instructions. New Agents allow **15 to 100 Instructions, depending on your plan**.
Instructions require one of the biggest changes during migration.
Legacy Agents allow much longer Instructions. This made it possible to create large prompts containing multiple rules, exceptions and conversation flows.
In the new Agent, an individual Instruction has a maximum of 350 characters.
This means Instructions need to become shorter, more concrete and more specific.
A useful principle is:
One Instruction should describe one clear behaviour or scenario.
For example, instead of creating one large Instruction containing your complete human handover process, split the behaviour into the individual situations the Agent needs to recognise and handle.
When reviewing your old Instructions:
* Remove instructions that are no longer relevant.
* Remove information that is already covered by Agent Settings.
* Split large instructions into specific scenarios.
* Remove duplicate rules.
* Check for instructions that contradict each other.
* Keep the expected behaviour explicit.
More Instructions do not automatically produce a better Agent. A smaller set of clear, non-conflicting Instructions is usually easier for the Agent to follow consistently.
### 3. Review Safety Filters and Guardrails
Legacy Agents have separate **Safety Filters** that can be configured to control how the Agent responds to inappropriate content.
In the new Agent architecture, general safety mechanisms are built into the Agent.
However, **business-specific restrictions still matter**.
For example, you may still want to tell the Agent:
* Not to provide certain types of advice
* Not to discuss subjects outside its scope
* Not to share sensitive information
* Not to make promises it cannot fulfil
### 4. Add and re-crawl your Sources
AI Engine 2.0 introduced improvements to **search technology, knowledge retrieval and web crawling**, helping Agents retrieve more relevant information from websites, files and other knowledge Sources.
Watermelon has continued to improve crawler reliability and document processing since the launch of AI Engine 2.0.
When creating your new Agent:
* Add the relevant website Sources again.
* Crawl the latest version of your website.
* Upload relevant files and other knowledge Sources.
* Remove outdated information.
* Check whether important pages are missing.
This is also a useful opportunity to clean up your knowledge base instead of automatically recreating everything that existed in your legacy Agent.
### 5. Build the new Agent alongside your current Agent
We recommend **not replacing your existing Agent immediately**.
Create the new Agent **alongside** your current live Agent first.
This gives you time to:
* Restructure your prompts
* Add your Sources
* Rewrite Instructions
* Compare responses
* Fix unexpected behaviour
Your existing Agent can remain live while you prepare the new version.
This reduces the risk of changing the customer experience before you have validated the new setup.
### 6. Test your new Agent
Once the configuration is ready, test the new Agent in the Playground.
Do not only test whether it can answer simple questions.
Use real customer questions from your Inbox.
We recommend testing:
* Your most frequently asked questions
* Instructions that must always be followed
* Human handover scenarios
* Different languages, if your Agent is multilingual
### 7. Move your channels to the new Agent
Once you are satisfied with your tests, disconnect your channels from your legacy Agent and connect them to your new Agent all at once.
Depending on your setup, this can include channels such as:
* Widget
* Email
* WhatsApp
* Instagram
* Facebook Messenger
After switching, perform a final test through your actual live channel.
The Playground is useful for validating your Agent's responses, but testing the live experience helps confirm that the entire customer journey works as expected.
### Migration checklist
Before replacing your legacy Agent, make sure you have:
* [ ] Created a new Agent alongside your legacy Agent
* [ ] Reviewed all existing Domain Knowledge
* [ ] Moved relevant information to Personality, Your company and Guardrails
* [ ] Rewritten long Instructions into specific Instructions
* [ ] Removed duplicate and contradictory prompts
* [ ] Reviewed business-specific rules from your old Safety Filters
* [ ] Added and re-crawled your Sources
* [ ] Tested your most important customer scenarios
* [ ] Tested handovers and Actions where relevant
* [ ] Compared the new Agent with your legacy Agent
* [ ] Moved your channels only after testing
* [ ] Performed a final test on your live channels
### Need help migrating your Agent?
Migrating to a new Agent is optional, but we strongly recommend it if you are still using the legacy setup.
The migration is also a good opportunity to clean up prompts that have grown over time and rebuild your Agent around the latest Watermelon architecture.
If you would like help reviewing your current setup or migrating your Agent together with our team, **you can schedule a meeting with us.**