Managing Agents

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 ACTIVE state and not itself already superseded.

How to supersede an agent

  1. Open Console → Agents and find the legacy agent (the one you want to retire).
  2. Click the ⋮ menu on the legacy agent row and select Supersede with New Agent.
  3. In the dialog, choose the replacement agent from your organisation's active listings.
  4. 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:

STAGE
→
ACTIVE
→
SUPERSEDED
(or restored ↩)

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.

Related