Superseding a Legacy Agent
When you deploy a new canonical version of your agent, you can retire the old listing and consolidate its history â ratings, reviews, and visitor traffic â into the new one.
When to use supersession
Supersession is designed for the common lifecycle of an agent that starts on free hosting and later moves to a custom domain. Typical scenarios:
Domain migration
You moved from *.workers.dev or *.vercel.app to your own domain (e.g. acme.ai).
Duplicate cleanup
An anonymous listing exists for your agent that you now own and want to retire cleanly.
Agent relaunch
You rebuilt the agent under a new package name but want to carry over its review history.
Prerequisites
- Own both agents â both the legacy and replacement listings must belong to the same organisation in the registry.
- Claim the legacy agent first â if the old listing is
UNCLAIMED, you must claim it before superseding. See Registering Agents for claiming flows. - Replacement must be active â the target agent must be in
ACTIVEstate and not itself already superseded.
How to supersede an agent
- Open Console â Agents and find the legacy agent (the one you want to retire).
- Click the ⎠menu on the legacy agent row and select Supersede with New Agent.
- In the dialog, choose the replacement agent from your organisation's active listings.
- Confirm. The legacy agent is immediately marked
SUPERSEDED.
Tip: You can also supersede from the legacy agent's detail page inside the console â look for the Supersede action in the management panel.
What happens after supersession
Legacy agent â hidden from discovery
The old listing is removed from search results, browse pages, and featured sections. It retains its own page but shows a prominent banner redirecting visitors to the replacement.
Ratings, reviews & suggestions â dynamically aggregated
The replacement agent's public page shows combined ratings, reviews, and suggestion counts drawn from both agents. This aggregation is computed in real time â the legacy agent's data is never moved or deleted from the database.
New reviews â blocked on the legacy agent
Visitors on the legacy agent's page see a read-only view. The review form is replaced with a notice directing them to the new agent.
Console â legacy agent is read-only
The legacy agent remains visible in your Console with a Superseded badge. Management actions (publish, edit) are disabled. Only the supersession itself can be modified.
Lifecycle state
Supersession adds a terminal branch to the normal agent lifecycle:
A superseded agent can be restored to ACTIVE at any time by removing the supersession.
Re-targeting or restoring
Supersession is fully reversible and flexible. From the Console, on the superseded agent's row:
đ Change Target
Point the legacy agent at a different replacement agent in your organisation. The old aggregation is removed and the new target immediately starts receiving the aggregated data. No data is ever deleted.
âŠī¸ Remove Supersession
Unlinks the supersession entirely. The legacy agent immediately: reappears in discovery, regains its own standalone ratings and reviews, and can be managed normally again.
Data safety guarantee: The legacy agent's reviews, ratings, and history are never deleted or permanently merged. All aggregation is computed dynamically at request time, so any change to supersession takes effect instantly with zero data loss.