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.
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.
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.If you’ve reached your agent limit, please contact 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 eachNew 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
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
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
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
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
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
6. Test your agent
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
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
- Facebook Messenger
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