Retire and delete a Voice Agent without leaving numbers attached

Before deleting a Voice Agent, move its incoming numbers to a working replacement and verify that calls can still reach the intended destination. Deleting the agent is not a shortcut for changing a number’s route, cancelling a number rental or removing a team member.

1. Decide what will replace the agent

You need permission to manage the Voice Agent and any incoming numbers whose routes you intend to change. Identify the exact agent by name and reference. Keep a private copy of business wording or knowledge you are entitled to retain before beginning. Do not assume deletion has an undo button or that a report can reconstruct the full configuration.

Prepare the replacement: another published Voice Agent, a supported team destination or another incoming destination actually offered for the number. Review hours and no-answer behavior. A replacement name in a selector is not evidence that its receiving system is ready.

2. Move attached incoming numbers deliberately

1. Inspect the agent’s Phone Numbers area and the saved destination of every affected number.
2. Open the intended number’s routing controls. Select the approved replacement and save through the ordinary number-routing workflow.
3. Wait for the saved result, then reopen the number to confirm the actual destination. Do not rely on an unsaved dropdown.
4. Repeat for each attached number, keeping a private checklist so one does not get overlooked.
5. Verify the replacement path with an authorized call before retiring the old agent. Check ringing, two-way audio and the intended fallback.

3. Resolve active preparation work

Return to the old agent and read its current state. Deletion is guarded while publishing or knowledge work is active and while numbers remain attached. Let that work finish and refresh the relevant view; do not try to bypass a blocker by changing unrelated account settings. If the Portal still reports an attachment, recheck the saved incoming destination rather than merely hiding the number from your checklist.

4. Delete the correct agent once

1. Open the existing agent in Studio and review its name, reference and remaining attachments.
2. Select the offered Delete action and read the confirmation before accepting. This changes the agent and can remove its prepared resources.
3. Wait for the result. Do not double-click, switch agents or assume a network timeout means nothing happened.
4. Refresh or reopen the agent list to confirm whether the agent is gone or deletion still needs recovery.

5. Handle a pending or failed response

Some cleanup work can finish after the initial request. If the Portal says the deletion is saved and will retry safely, treat it as pending recovery. Do not recreate an agent with the same purpose and assume the old one is still usable. Preserve the message and time; ask Support about a persistent pending state instead of repeatedly forcing deletion.

A complete deletion result and working incoming calls are separate checks. Inspect the moved numbers again and verify the intended replacement remains selected. This operation does not cancel a rented phone number, alter your whole account’s routing package or delete a SIP team member. Use the dedicated workflow if one of those is also required.

What to send Support

Provide the old agent reference, the affected number references without unnecessary personal information, the intended replacement, operation time and exact visible error. Include a public call reference if the replacement does not ring. Keep exported knowledge, credentials and full customer call data private.

Related guides

• Prepare an AI voice agent
• How to order a DID Number and start making calls
• Change an incoming number’s destination through the IllyVoIP API
• Build and maintain your Voice Agent knowledge

Reviewed 12 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.