Retiring Production Agents: The Checklist Nobody Wrote

Every conference talk covers the launch. Tool calls, context windows, the demo that ships. The end of the lifecycle gets nothing.

Teams that put agents in production through 2025 are now making their first retirement decisions. The customer support agent running on a model two generations behind. The internal research tool with 18 months of edge cases compressed into its system prompt and credentials wired into four systems no one mapped. The QA agent quietly invoking three other agents whose owners have no idea they are being called.

Shutting these down is messier than it looks. An agent is not just code. It is an identity with credentials, a memory store with accumulated patterns, a service with downstream consumers nobody enumerated. Archive the repo and close the ticket and you leave API keys live, service accounts provisioned, and calling agents broken on a delay timer. Security teams have a name for what you just created: ghost agents — retired in intent, live in practice, nobody watching.

Treat retiring an agent exactly like decommissioning a microservice. Version the prompt contract. Run a shadow period. Extract the patterns the agent learned in production before you wipe it. Communicate the deprecation with a sunset date downstream owners can plan against. The structural analogy makes the right behaviors obvious. Skipping any phase has a specific cost — and the cost compounds.

Retirement is harder than launch because the cost of doing nothing looks small until it is not.

Five triggers that should be treated as decisions, not vibes:

Performance has structurally degraded. Not a bad week. A trend. The base model is two generations old. Eval scores that looked acceptable six months ago now sit well under the current baseline. The gap between what the agent does and what a successor would do is wide enough to show up in the business numbers. That is a retirement signal, not a tuning task.

The use case has drifted. The workflow the agent was designed for no longer runs the same way. Teams keep agents alive because "it still mostly works" — while the definition of "works" quietly migrated. An agent optimized for a workflow that no longer exists is not an asset. It is maintenance debt with a per-call inference bill.

The base model is being deprecated. Providers set end-of-life dates. When the underlying model retires, every agent built on it migrates or shuts down. Migration means re-evaluating against the new model on your existing eval set — not assuming behavior transfers cleanly. It rarely does.

The business context shifted. A pivot. An acquisition. A process redesign. The workflow this agent was built to accelerate no longer exists in its original form, and rebuilding the agent around the new shape is more expensive than starting over.

Nobody can explain what it does. The most expensive trigger. The original author is gone. Documentation is thin or missing. The agent runs because the agent runs. Continuing to operate a system whose behavior nobody owns is a slow-burn incident waiting for a stakeholder to pull on the wrong thread.

Software engineering has a developed vocabulary for turning services off: deprecation notices, shadow periods, contract versioning, sunset dates. Patterns for notifying downstream consumers and handling clients who missed the migration window.

Agents need the same vocabulary. The parallel is closer than it looks.

A production agent has a public interface (the prompts it accepts, the outputs it produces), downstream consumers (orchestrators, calling agents, humans wired to its behavior), internal state (memory, embeddings, learned patterns), and credentials granting access to external systems. These map nearly one-for-one onto a microservice's API contract, client applications, database state, and service account permissions.

The analogy breaks in one direction that matters: an agent's "API" — the system prompt — is rarely version-controlled with the rigor applied to an HTTP endpoint. That gap is exactly where retirement goes wrong. Downstream systems depending on a specific output format, a specific tool call pattern, or a specific persona behavior have no contract to reference. When the agent disappears, they break silently. The orchestrator falls back to a default value. Nobody notices for two weeks. By then the trail is cold.

The retirement pipeline borrows from microservice patterns and adapts them for the shape of an agent. Order matters.

Skip knowledge extraction before the shadow period and you lose institutional memory the moment the prompt is wiped. Run the hard shutdown before credential revocation and you mint a ghost identity with live permissions on Day 0. Each phase absorbs failure modes the next one cannot reach. The order is not arbitrary.

The shadow period is the safest transition mechanism in the retirement toolkit, and the most frequently skipped.

The mechanism: before the old agent goes dark, the successor runs in parallel. Same inputs, parallel outputs. The successor's responses are logged but not acted on. You are comparing behavior distributions — not running an A/B test on user experience.

How to run it: route production traffic to both agents simultaneously. Collect both outputs. Score equivalence — semantic similarity on a shared eval set works better than exact string matching for natural-language outputs. The goal is confirming the successor handles the same failure modes, declines the same request categories, and produces outputs in the format downstream systems are parsing.

Shadow mode finds the contracts no documentation captured. One platform team running a shadow period for an invoice processing agent discovered that a downstream orchestrator was extracting a specific field — confidence_score — from the retiring agent's structured output. The successor did not include that field. No automated test had flagged it. The orchestrator degraded gracefully, falling back silently to a default value. The divergence only appeared in the comparison delta between the two outputs. That is exactly what shadow periods are for. The implicit contract that never made it into a schema.

Stakeholders need a structured deprecation notice that answers four questions without requiring a follow-up: what is changing, when it stops, what the migration path is, who to contact when something breaks.

Borrow from the API deprecation playbook. Announce at least 30 days before shutdown for anything with integration dependencies. For any hard integration — another agent calling this one, a webhook pointed at the endpoint — 30 days is the floor, not the ceiling. If the shutdown will break a calling agent whose owning team needs to update their tool config, test it, and ship the change, 14 days is not lead time. It is a forced incident.

One stakeholder is consistently underestimated: the data and compliance team. They approve the data disposition plan before shutdown begins, not after. Vector stores containing PII have retention and deletion requirements that can extend the retirement timeline by weeks. Find this out in Phase 1, not the day before cutover.

By this point, the successor is live, stakeholders have acknowledged the deprecation, and the data disposition plan is signed off. The hard shutdown is the shortest phase. All that remains is execution.

Every item below executes on the same day the agent stops receiving traffic. The most common failure mode at this stage: completing the cutover and parking the credential revocation as a follow-up ticket. That gap is the entire mechanism by which ghost agents come into existence. Close it the same day or do not call the agent retired.

The security dimension of agent retirement gets less airtime than the operational one. It is the more urgent dimension.

Machine identities — service accounts, API keys, OAuth tokens issued to automated systems — are growing faster than human identities in most enterprise environments ^[3]. The structural problem: organizations apply real lifecycle discipline to human identity (offboarding checklists, IAM reviews, periodic access audits) and almost none of it to machine identity.

An agent that is retired informally — code deleted, repo archived, ticket closed — does not lose its credentials. The service account it used to hit the CRM is still provisioned. The API key for the webhook integration is still active. The OAuth token scoped to the data warehouse connector is still valid. The agent is gone. The blast radius is not.

Security teams call these ghost identities: credentials from systems that no longer exist, still live, nobody watching. They are a quiet privilege escalation surface. An attacker who finds a valid scoped API key with read access to customer records does not care that it belonged to an agent retired six months ago. They care that it works.

Teams that have run systematic audits report finding service accounts provisioned for agents that were never formally retired — live credentials attached to dead systems, sometimes still holding permissions that were never scoped down from the original "move fast" deployment. This is not a hypothetical attack vector. It is a cleanup task that compounds with every agent that skips Phase 5.

Gartner projected that 40% of enterprise applications would embed task-specific AI agents by 2026, up from under 5% in 2025 ^[5]. At those numbers, informal retirement does not just create operational mess. It creates a credential sprawl problem that is genuinely difficult to audit retroactively — and the audit gets harder every quarter.