This article covers the concepts, gotchas, and step-by-step patterns for migrating a legacy Zendesk AI agent (bot builder / Answer Bot-style) to the new AI agents experience. Pair this with the migration assignment doc, which covers the task/deadline side.
Deadlines
- August 31, 2026: Zendesk stops technical development on AI agents Essential and legacy functionality (bot builder, answers, intents). Critical bug fixes only after this.
- December 10, 2026: Full removal. Legacy flows stop working entirely.
Step 1: Identify what you're migrating
Open the AI agent in Admin Center → AI → AI agents → AI agents:
- No Intents or Answers tab → Essential AI agent : knowledge-based only, simpler migration.
-
Has an Answers tab (and possibly Intents) → legacy AI agent with custom scripted flows: more involved migration, use the mapping tables below.
Step 2: Concept mapping (legacy → new)
| Legacy concept | New AI agents equivalent |
| Bot builder | Dialogue builder |
| Answers | Dialogues/Procedures |
| Intents | Use cases |
Step-type mapping
| Old step type | New block type |
| Send message | AI agent message |
| Present options | Customer message |
| Show help center articles | Generative replies |
| Add carousel | Carousel (to add link and images) |
| Ask for details | AI agent message +customer message |
| Ask if question resolved | Customer message |
| Make API call | Integration or action flow |
| Transfer to agent | Escalation |
| Branch by condition | Conditional |
| Add business hours condition | Availability |
| Link to another answer | Link to |
| Set variable | Any block with an added action that sets a conversation parameter |
Step 3: Dialogues vs. generative procedures
The new AI agents experience gives you two ways to build a use case's response, you choose per use case, not for the whole agent (a mix is called a "hybrid AI agent"):
| Dialogues | Generative procedures | |
| Style | Scripted, branching, precise | Free-text instructions, AI adapts in real time |
| Buttons/carousels | ✅ Supported | ❌ Not supported - no rich formatting at all |
| Setup effort | Higher | Lower |
| Best for | Anything needing exact control, clickable options, or a fixed sequence | Open-ended, judgment-based flows |
| Email channel | Not Supported | ✅ Supported |
| Where to set it | Open the use case → find the Reply method field → select Dialogue | Open the use case → find the Reply method field → select Procedure |
⚠️ Channel limitation: Advanced email AI agents can't use dialogues at all, only generative procedures. If you're building for email and only see the procedure option, that's expected, not a bug.
⚠️ Buttons/multiple choice: If a legacy flow relied on clickable multiple-choice, it must be a dialogue - generative procedures cannot reproduce buttons. This is one of the most common "doesn't map cleanly" cases.
Step 4: Recreating multiple-choice / "Present options"
Legacy's "Present options" step doesn't have a direct one-block equivalent - it's a two-block pattern:
⚠️ Messaging channels only. The two-block pattern below uses the "Button clicked" scenario, which is not available on email channels.
- AI agent message block: write the message to set the buttons after
- Customer message block (added right after): set the scenario to "Button clicked" and specify which button text triggers it. Build a separate branch per button using the plus icon.
Also: "Button clicked" and "Link clicked" scenarios can't be used at the same level in a dialogue- if you need both, split them into separate AI agent messages.
Step 5: Recreating the start-of-conversation menu.
Legacy's "Send a greeting and suggest answers" (dropdown-driven, up to 10 answers as buttons) maps to the Welcome reply in the new experience. It lives in your use cases list, not in a Settings menu:
- Go to Content → Use cases. Look for the item tagged System replies: this is where system replies including the Welcome reply appear. (There is no "Settings" section in the new AI agents interface.)
- Open the Welcome reply: this opens directly into the dialogue builder. Procedures are not available here, since clickable buttons are the whole point and buttons require a dialogue.
- Write your greeting in the pre-populated AI agent message block.
- Add a Customer message block immediately after it. Set the scenario to "Button clicked" and specify which button text triggers it. Build a separate branch per button using the + icon. (This follows the same two-block pattern as Step 4.)
- In the dialogue there is automatic translation which should avoid the extra work of translation per dialogue. You need to add the different languages in the bot's settings to allow automatic translations.
Common "doesn't map cleanly" cases to watch for
- Multiple-choice buttons needed on an email flow: no equivalent; rethink as text-based.
- A legacy flow spanning both messaging and email: this becomes two separate AI agents, since one AI agent = one channel type.
- Heavy use of buttons within a generative procedure: not possible; that portion of the flow needs to be pulled out into a dialogue instead (hybrid setup).
- Anything relying on API calls: these become integrations/action flows and generally need more setup time than a simple message-based step.
- Legacy flows combining images, links, and escalations: The new 'Carousel' block does not support flow continuation after the carousel. For these flows, use an 'AI agent message' block instead and include the link as a plain text link (no buttons) if you need the flow to continue, images won’t be possible to add.
- Buttons vs. Links in Customer message blocks: While you can add multiple buttons in a 'Customer message' block, adding a 'Link' often breaks flow continuation. Stick to button scenarios for flow branches, or use plain text links within an AI agent message if you need to provide a link while keeping the flow active.
Publishing
Activating a new AI agent on a channel replaces the old one immediately, any in-progress conversation with the old agent loses its context. Publish during low-traffic hours.
Contributing to this playbook
If you hit a migration case not covered here, add it under "Common doesn't map cleanly cases" with what you tried and what worked, this is meant to grow as more consultants migrate real flows.