Retiring or Swapping an AI Agent Without Losing Its Knowledge
Picture a team that swaps its support agent onto a faster model and a new framework. On day one the replacement has forgotten the refund exceptions, the escalation rules, and three months of tuned voice.
Picture a team that swaps its support agent onto a faster model and a new framework. On day one the replacement has forgotten the refund exceptions, the escalation rules, and three months of tuned voice. The fix is to keep what the agent knows outside the agent. In Sanity, Knowledge Bases and agent instructions are structured documents in the Content Lake, served through the Sanity Context MCP endpoint. The replacement connects to the same source, so the knowledge never has to move.
The stakes are higher than they look. If knowledge lived in a system prompt string, a fine-tune, or a framework's thread storage, it leaves when the agent does. Usually nobody notices until customers start getting confidently wrong answers. Vendors can also force the swap on their own schedule. OpenAI deprecated its Assistants API on August 26, 2025, and set removal for August 26, 2026.
This guide treats swapping an agent as a content migration, not a code rewrite. Separate the knowledge from the runtime, take inventory of it, point retrieval at a source the organization owns, and only cut over when the new agent passes the same eval set as the old one.
What does an AI agent know, separately from the model that runs it?
An AI agent knows four kinds of context, and none of them belong to the model or the framework that runs it. The model is a reasoning engine you rent. The framework is the plumbing that calls tools and runs the loop. What makes a particular agent useful (its rules, its facts, and its history) is context, and context comes in four kinds, each with its own lifetime and owner.
Static instructions are the system prompt: role, voice, escalation rules, and the things the agent must never say. They change on a release cadence and belong to product, brand, support, and compliance. Retrieved content is the knowledge the agent looks up, such as product docs, policies, and help articles. It changes slowly, and the content team owns it. Per-turn state is what your application injects for a single turn, like the signed-in user's plan or cart. It lasts one turn, and your app owns it. Agent-authored notes are the memory, summaries, and distilled context an agent writes for its own future self across sessions.
This split matters for a swap because each kind moves differently. Your application regenerates per-turn state, so a new agent gets it for free as long as the integration contract holds. Retrieved content and static instructions are durable assets that people spent months getting right, and they have to survive the swap intact. Agent-authored notes sit in between. They can be valuable, but they're often in a format specific to the framework that wrote them.
Teams that treat context as one blob tend to underbuild three of the four kinds. A common pattern is a single prompt file that mixes brand voice, a pasted FAQ, and a few hardcoded customer rules. When the agent is replaced, someone rewrites that file for the new framework, and the parts nobody remembers adding quietly disappear.
Here's a practical test for any agent in production. For each of the four kinds of context, can you say where it lives, who owns it, and how a different model would read it? If the answer for instructions or retrieved content is "inside the agent," you can't retire that agent without losing what it knows.
Why is knowledge lost when you replace an AI agent?
Knowledge gets lost when an agent is replaced because it was kept in places that belong to the agent rather than to the organization. Three places account for most of the loss: prompt strings in code, fine-tuned model weights, and framework-specific memory stores.
Prompt strings in code are the most common. In many teams the system prompt is a string in a file such as prompts.ts, versioned in git and editable only by engineers. That works until the framework changes. Then someone has to copy the strings by hand into a new template format, and the brand, support, and compliance owners who shaped those instructions have no way to check what made it across.
Fine-tunes are even harder to carry over. Behavior learned through fine-tuning lives in the weights of one model. Move to a different base model and the tuning stays behind, so you either repeat the training on the new model or accept that the behavior is gone. Facts that should have been retrievable content end up frozen inside the model you're trying to leave.
Framework-specific memory stores keep threads, conversation history, and file indexes in the vendor's own format. The clearest recent case is OpenAI's Assistants API, deprecated on August 26, 2025, with removal on August 26, 2026. Teams using it have to move Assistants, Threads, Runs, and vector-store File Search to the Responses and Conversations APIs. Nothing about their business changed, but their agent's knowledge and memory still have to be moved by hand because they lived inside the framework.
Agent platforms that run their own retrieval create a similar dependency. If a platform crawls your site or asks you to load data into its index, that index belongs to the platform, and replacing the platform means rebuilding it. Vector databases fed by a sync pipeline are more portable in principle. But the embeddings are tied to one embedding model and a separate sync job, and the instructions still live somewhere else.
All three cases have the same root cause. The agent became the system of record for knowledge it should only have been reading.

A deprecation is a forced agent swap
What should an AI agent migration checklist include?
An AI agent migration checklist has four steps, in this order: take inventory of the knowledge sources, export memory, re-point retrieval, and run evals against the same golden dataset before cutover. Teams that skip or reorder these steps end up with a new agent that passes a demo and fails on real traffic.
Step 1: take inventory of the knowledge sources. Go through the four kinds of context and write down where each one lives today. List every system prompt and its owners, every document set the agent retrieves from, every hardcoded rule in application code, and every place the framework keeps memory. Flag anything that exists only inside a fine-tune, because you'll need to rewrite that behavior as instructions or retrievable content.
Step 2: export memory. Pull conversation history and any agent-authored notes out of the old framework before it's switched off or removed. Export them into a neutral format you control, then decide what's worth keeping. Most raw threads are more useful as eval material than as live memory.
Step 3: re-point retrieval. The new agent should read from the same knowledge source as the old one, not from a fresh copy. If the old agent's index lived inside its platform, this is when you move that knowledge into a source the organization owns, so the next swap is just a configuration change.
Step 4: run evals against the same golden dataset. An eval suite is a frozen set of representative conversations, twenty to start, each scored against a rubric you wrote. Run the same suite against the outgoing agent and the replacement. The bar for cutover is that the bench stays green: the new agent matches or beats the old one on the same conversations, scored the same way.
The order matters because each step depends on the one before it. You can't re-point retrieval you haven't inventoried, and an eval comparison means nothing if the two agents are reading different knowledge. Keep the old agent running in parallel until step 4 passes. Then retire it, with its memory already exported.
How do you export an AI agent's memory before retiring it?
To export an AI agent's memory, separate conversation history from agent-authored notes, pull both into a format you own, and decide which parts the replacement actually needs. Memory is the hardest of the four kinds of context to move. The framework usually writes it, in its own format, and it's rarely designed to leave.
Start by telling the two apart. Conversation history is the raw record of turns between users and the agent. Agent-authored notes are what the agent wrote for itself: summaries, inferred preferences, and facts it decided to remember across sessions. History is large and mostly useful for evaluation and analysis. Notes are small and may help the next agent, but only if they're accurate and still relevant.
Next, export before the deadline, not after. Framework stores and vendor thread APIs can be deprecated on a schedule you don't control. Pull the data while the old APIs still respond, and write it somewhere neutral. Key it to stable user or account identifiers rather than framework-specific thread IDs.
Then sort what you exported. Notes the old agent wrote can carry the old agent's mistakes, so review a sample before loading any into a new agent. Facts that hold up over time, like a product limitation the agent kept noting, usually belong in the shared knowledge source as reviewed content rather than in one agent's private memory.
Sanity Context helps with the history half of this. Its telemetry integration for the AI SDK includes a saveConversation primitive that writes conversations back into Sanity. You can then run conversation classification from a scheduled function over those saved conversations. The conversations, their scores, and the source content the agent queried all sit in one place, independent of the agent that produced them. That gives you real traffic to draw on when you build the golden dataset for the eval step.
Agent-authored memory notes are a different matter. Plan their export with your framework's own tooling, and treat the result as material to review, not something to load into the new agent as-is.
How does Sanity Context keep agent knowledge independent of any one agent?
Sanity Context keeps knowledge independent of any one agent by putting Knowledge Bases and agent instructions in the Content Lake as structured content. It serves them through a hosted, read-only MCP endpoint that any agent loop can connect to. The agent reads the knowledge but doesn't own it. To swap the agent, you point a new client at the same Sanity Context MCP endpoint, and the knowledge stays where it is.
This is the idea of a shared foundation behind Sanity as the AI Content Operating System, the intelligent backend for companies building AI content operations at scale. Legacy CMSes create silos and add AI as an afterthought. Sanity is built for agents, with one structured layer connecting teams, systems, surfaces, and agents.
Sanity Context has three parts: an MCP, a knowledge base, and an ingest path. Retrieval runs in one of two modes. GROQ mode queries the dataset at request time. With dataset embeddings turned on, a single GROQ query can combine structured filters with semantic similarity, using text::semanticSimilarity() as an argument to score(). Knowledge Base mode serves an index built ahead of time. You can override the mode for one connection with ?mode=groq or ?mode=knowledge_base, which helps when you run the old and new agents side by side during cutover.
A Knowledge Base is a pre-built index over sources you choose. It belongs to the organization rather than to a project or an agent, and it can draw on more than one project. It has a purpose, an outline (every entry path plus a one-line summary, served by the initial_context tool), entries, issues, and instructions. Entries are Markdown written from the sources, with citations back to the original, and they can't be edited by hand. Instructions are standing decisions, such as which source to trust when claims conflict. Each one is tied to its sources, so a build retires it automatically when those sources change.
That last property matters most in a swap. The new agent inherits decisions that stay current with their sources, not a stale prompt someone forgot to update.
Knowledge Bases are in Beta
How do you govern an AI agent handover with versioned instructions and Content Releases?
To govern an agent handover, treat the agent's instructions as versioned content with named owners, stage the change with Content Releases, and let an eval gate decide when it ships. A handover changes customer-facing behavior, so it deserves the same review as a homepage launch.
In Sanity, the system prompt can be a document instead of a string. An agentPrompt schema splits it into fields such as role, voice, userContext, escalation, and mustNotSay. The split is about access control, not formatting. Brand owns voice, product owns how the agent uses user context, support owns escalation, and compliance owns the never-say list. Because the document lives in the Studio, it comes with real-time collaboration, version history, scheduled publishing, and rollback. Update it once and the website, apps, and customer agents stay in sync.
During a swap, those fields are what the new agent inherits. Nobody retypes instructions into a new framework's template. The replacement reads the same document, and the version history shows exactly what changed between the agent you retired and the one you shipped.
Content Releases handle the timing. Put any instruction edits the new agent needs into one release, along with the content changes that go with them. Then preview the release and schedule it. The same release that ships a homepage change can ship a prompt change, so the instruction update, the retrieval switch, and the website copy go live together. If the new agent misbehaves after cutover, rollback restores the previous version of the instructions without a code deploy.
The principle that holds this together is to author instructions like content and gate them like code. Every prompt change runs the eval bench in CI before it can ship, and a model swap is just one more change the bench has to pass. Run the frozen set of conversations against the replacement with the same instructions and the same Knowledge Base. When it scores green, you can retire the old agent knowing its knowledge never left.
Where agent knowledge lives when you swap agents: Sanity Context compared
| Feature | Sanity | Pinecone + sync pipeline | Sierra AI | Prompts in code + framework memory |
|---|---|---|---|---|
| Where shared knowledge lives | In Content Lake documents and Knowledge Bases (Beta) owned by the organization, served through a hosted, read-only Context MCP endpoint that any agent loop can connect to | Vectors in a Pinecone index, filled by a sync pipeline you build and run. The source content stays in another system, so knowledge is split across two places | In the platform's own index, built by loading data or crawling your site. The index belongs to the platform, not to your content source | Pasted into prompt strings or kept in the framework's retrieval and memory stores, in formats specific to that framework and that agent's codebase |
| What a new agent connects to after a swap | The same Sanity Context MCP endpoint, so the knowledge doesn't move. You can set ?mode=groq or ?mode=knowledge_base per connection while testing old and new agents side by side | The same index, if the new agent uses the same embedding model. Your retrieval glue code still has to be re-pointed and re-tested in the new framework | Replacing the platform means rebuilding the index somewhere else, because the platform holds the crawled or loaded knowledge | Strings and memory have to be ported by hand into the new framework's templates and stores, with engineers doing the copying and review |
| Changing the embedding or retrieval approach | Dataset embeddings live with the content in the Content Lake, and GROQ mode combines structured filters with text::semanticSimilarity() inside score() in one query | Assembled by you: swapping embedding models can force a full re-embed through your pipeline, which you schedule, run, and verify yourself | Handled by the platform on its own terms. The retrieval setup is part of the platform, not a portable asset you can take to another agent | Depends on the framework's retriever and vector store integrations, so changing frameworks usually means rewiring retrieval code |
| Who can edit agent instructions | An agentPrompt document in the Studio with fields for role, voice, escalation, and mustNotSay, so brand, support, and compliance each edit their own part | Out of scope: Pinecone holds vectors, so instructions live in your application code or in another tool your team picks | Set up through the platform. Whether instructions and their history can move elsewhere depends on the vendor's export options | Versioned in git and editable only by engineers. Brand, support, and compliance owners review changes indirectly, if at all |
| Staging and rolling back the handover | Content Releases group instruction and content changes for preview and scheduled publishing. Version history and rollback restore the previous prompt without a deploy | Index changes go live when your pipeline writes them. Staging needs separate namespaces or indexes that you create and manage | Follows the platform's own release and testing workflow, separate from how your website and other content are staged | Ships with a code deploy. Rollback means a git revert and a redeploy, tied to the engineering release schedule |
| Conversation history for evals | saveConversation in the AI SDK telemetry integration writes conversations back into Sanity, next to the content the agent queried, for scoring and building a golden dataset | Not a conversation store. History and eval data live in whatever logging or observability tools you add alongside it | Conversation history lives in the platform, so export it before you retire the platform if you want it in your eval set | Threads sit in the framework or vendor store. OpenAI Assistants Threads, for example, have to move to the Conversations API before removal on August 26, 2026 |