> ## 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. > [!NOTE] > > **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? Open your Agent and check which configuration you see: * **Domain Knowledge** → follow this guide. * **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? Legacy Agents use a different prompt structure. In a legacy Agent, **Domain Knowledge has a higher priority than Instructions**. In a new Agent, **Agent Settings and Instructions have equal priority**. This helps the Agent combine general configuration with scenario-specific Instructions more consistently, as long as your prompts do not contradict each other. The migration is therefore a good opportunity to simplify and improve your existing configuration. 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. > [!WARNING] > > **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. Create a new agent Start by creating a new Agent alongside your current live Agent. Your legacy Agent can stay connected to your channels while you prepare and test the new version. This lets you complete the migration without immediately affecting your live customer experience. > [!NOTE] > > If you've reached your agent limit, please contact [support@watermelon.ai](mailto:support@watermelon.ai) for further help. ### 2. 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 **business context and general processes**. For example: * What your company does * Products and services * Relevant company context * General processes the Agent should understand Detailed factual information is usually better placed in Sources. ### Guardrails Use Guardrails for **what your Agent cannot or should not do**. For example: * Topics it should not answer * Information it must never share * Actions it is not allowed to perform * Claims or promises it should not make Legacy Agents also use separate Safety Filters. General safety is built into the new Agent, so you do not need to recreate these one by one. Only move **business-specific restrictions** from your old Safety Filters into Guardrails. **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?** Specific flows, exceptions and scenario-based behaviour should generally be handled through Instructions. ### 3. Add en re-crawl your sources Add the relevant Sources to your new Agent again. Re-crawl your website Sources so the new Agent uses the latest version of your content and benefits from the newer retrieval and crawling architecture. While migrating: * Crawl the latest version of your website * Upload relevant files * Remove outdated Sources * Check whether important pages or documents are missing * Move factual information out of prompts and into Sources where possible This is also a good opportunity to clean up your knowledge base. ### 4. Rewrite your instructions New Agents are designed around shorter, more specific Instructions. The number of Instructions available depends on your plan. See **Plan limits** for the current limits. When rewriting Instructions: * Use one clear scenario per Instruction * Define when the Instruction should apply * State the expected behaviour explicitly * Avoid overlap with Agent Settings * Remove duplicate Instructions * Resolve contradictory rules * Remove anything that is no longer relevant Specific flows and exceptions should generally be handled here rather than being placed in broad Agent Settings. ### 5. Review Actions and Human Handover Before testing the new Agent, review any **Actions** and **Human Handover** configuration used by your legacy Agent. Check that: * Required Actions are configured * Action Instructions still match the new Agent * Required information is collected before an Action runs * Human Handover triggers are configured correctly * Important handover flows still behave as intended Where possible, test these flows before moving your live channels. ### 6. Test your agent > [!TIP] > > We recommend **not replacing your existing Agent immediately**. Use the Playground to test the new Agent before replacing your legacy Agent. Use real customer questions from your Inbox and focus on: * Frequently asked questions * Important Instructions * Business rules * Actions * Human Handover * Important exceptions * Tone of voice * Different languages, if relevant If something behaves unexpectedly, first check whether your Agent Settings and Instructions contain duplicate or contradictory information. ### 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.** This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.