# Model Lifecycle

AI model providers regularly release new models and retire older ones. Seclai tracks these lifecycle changes automatically and keeps you informed — through in-app alerts, email notifications, and actionable replacement recommendations — so your agents always run on supported models.

## Overview

Every prompt model in Seclai has a lifecycle managed by its provider (Anthropic, OpenAI, Google, etc.). When a provider deprecates or sunsets a model, Seclai:

1. **Detects the change** — checks model lifecycle status daily at 00:15 UTC
2. **Creates in-app alerts** — for every affected agent on your account
3. **Sends email notifications** — once per account per model (at 00:45 UTC)
4. **Suggests replacements** — successor, upgrade, and alternative models

You can monitor everything from the Agents page, individual agent detail pages, and via the API or MCP.

## Lifecycle Stages

Models move through three stages:

### Active

The model is fully supported and functioning normally. No action required.

### Deprecated

The provider has announced the model will be removed in the future. The model **still works** but you should plan a migration to a replacement model.

| Indicator        | Where                                   |
| ---------------- | --------------------------------------- |
| **Orange badge** | Agent list and agent detail pages       |
| **In-app alert** | Model lifecycle alert banner            |
| **Email**        | Sent once to the account's primary user |

### Sunset

The model has been fully removed by the provider and **no longer works**. Any agent step using a sunset model will fail at runtime. Immediate action is required.

| Indicator        | Where                                   |
| ---------------- | --------------------------------------- |
| **Red badge**    | Agent list and agent detail pages       |
| **In-app alert** | Model lifecycle alert banner            |
| **Email**        | Sent once to the account's primary user |

---

## Model Alerts

Seclai generates three types of model lifecycle alerts:

### Model Deprecated

Created when a model used by one of your agents is deprecated by the provider. The alert message includes the affected agent name, step names, and the model's sunset date (if known).

| Setting    | Value                                                      |
| ---------- | ---------------------------------------------------------- |
| Thresholds | None — triggers automatically when the model is deprecated |
| Default    | Enabled for all accounts                                   |

### Model Sunset

Created when a model used by one of your agents has been fully sunset. This is a critical alert — the affected agent steps will no longer function.

| Setting    | Value                                                  |
| ---------- | ------------------------------------------------------ |
| Thresholds | None — triggers automatically when the model is sunset |
| Default    | Enabled for all accounts                               |

### Newer Model Available

Created when a newer model in the same family is released (e.g., Claude Opus 4.6 when you're using Claude Opus 4). This is an informational alert — your current model still works fine.

| Setting    | Value                                                        |
| ---------- | ------------------------------------------------------------ |
| Thresholds | None — triggers automatically when a new release is detected |
| Default    | Disabled (opt-in)                                            |

## Alert Banner

The **Model Lifecycle Alerts** banner appears at the top of:

- **Agents list page** — shows all unread model alerts across the account
- **Agent detail page** — shows alerts specific to that agent

Each alert can be individually dismissed, or you can dismiss all at once. The banner polls for new alerts every 5 minutes.

---

## Model Recommendations

When a model is deprecated or sunset, Seclai recommends replacement models based on capability compatibility.

### Recommendation Types

Recommendations are grouped into three categories:

| Type             | Description                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| **Successor**    | The provider's officially designated replacement for this model. Shown first and highlighted.            |
| **Upgrades**     | Newer models in the same family — same provider, higher generation. Up to 5 shown.                       |
| **Alternatives** | Compatible models from other providers or families that match the required capabilities. Up to 10 shown. |

Each recommendation includes the model's capabilities (tool use, thinking, structured output), context window size, and a human-readable reason for the suggestion.

### Capability Filters

You can filter recommendations to match your requirements:

| Filter                                 | Description                                              |
| -------------------------------------- | -------------------------------------------------------- |
| <code>require_tool_use</code>          | Only show models that support tool/function calling      |
| <code>require_structured_output</code> | Only show models that support JSON output                |
| <code>require_thinking</code>          | Only show models that support chain-of-thought reasoning |
| <code>min_context_tokens</code>        | Minimum context window size                              |
| <code>min_output_tokens</code>         | Minimum output token limit                               |

### Recommendation Panel

When editing a prompt call step that uses a deprecated or sunset model, the **Model Recommendations** panel appears alongside the model selector. It shows the available replacements grouped by type and includes a **Use** button to switch models with one click.

---

## Email Notifications

Seclai sends email notifications for model deprecation and sunset events:

- **One email per account per model** — you won't receive duplicate notices
- **Includes affected agents** — the email lists every agent and step using the model
- **Sent at 00:45 UTC daily** — shortly after the lifecycle check at 00:15 UTC
- **Only for deprecated and sunset models** — "newer available" alerts are in-app only

### Opting Out

To stop receiving email notifications for a specific model alert type:

1. Go to **Agent → Alerts tab** (or the account-wide alerts settings)
2. Find the **Model Deprecated** or **Model Sunset** alert type
3. Toggle it **off**

When an alert type is disabled at the account level, both the in-app alert and the email notification are suppressed. Per-agent overrides can be configured for fine-grained control.

---

## Configuring Model Alerts

Model lifecycle alerts appear alongside the standard agent alert types in the **Alerts** tab. Unlike threshold-based alerts (like Consecutive Failures), model alerts have no configurable thresholds — they fire automatically when the condition is met.

You can:

- **Enable/disable** each model alert type independently
- **Configure per-agent** overrides that take precedence over account-wide settings
- **Set notification recipients** using the same distribution options as other alerts

By default, **Model Deprecated** and **Model Sunset** alerts are enabled for all accounts. **Newer Model Available** is disabled by default and must be opted in.

## Automatic Model Upgrades

Instead of waiting for a manual model migration, you can configure agents to automatically adopt successor models when one becomes available. This is controlled by the **auto-upgrade strategy** set at the agent level (or overridden per step).

### Upgrade Strategies

| Strategy                      | Behavior                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------ |
| <code>none</code>             | No automatic upgrade. The configured model is always used (default).           |
| <code>early_adopter</code>    | Switches to a successor model as soon as one is available.                     |
| <code>middle_of_road</code>   | Switches after a short stabilisation period following a new release.           |
| <code>cautious_adopter</code> | Switches only after a longer stabilisation period, preferring proven releases. |

The strategy can be set at two levels:

- **Agent level** (`prompt_model_auto_upgrade_strategy`) — applies to all Prompt Call and Insight steps that do not set a step-level override.
- **Step level** (`auto_upgrade_strategy` in the step definition) — overrides the agent-level setting for that step only.

### Auto Rollback

When an auto-upgraded model is in use, Seclai can automatically roll back to the previous model configuration if it detects quality or compliance regressions. Rollback creates a new agent branch commit reverting the step's model to the last known-good version.

Enable rollback at the agent level with `prompt_model_auto_rollback_enabled: true`. Like the upgrade strategy, this can be overridden per step with `auto_rollback_enabled`.

On a successful rollback, Seclai:

1. Creates a new branch commit restoring the prior model selection
2. Sends a `model_rollback_success` email notification
3. Emits a `PROMPT_MODEL_AUTO_ROLLBACK_SUCCEEDED` activity event

If no valid prior configuration is found, a `PROMPT_MODEL_AUTO_ROLLBACK_FAILED` event is emitted instead.

### Rollback Triggers

You can specify which failure signals trigger a rollback via `prompt_model_auto_rollback_triggers` (agent level) or `auto_rollback_triggers` (step level). When the field is null, the system defaults apply.

| Trigger                       | When it fires                                          |
| ----------------------------- | ------------------------------------------------------ |
| <code>agent_eval_fail</code>  | An agent evaluation criterion fails at the retry limit |
| <code>governance_flag</code>  | A governance policy flags the step output              |
| <code>governance_block</code> | A governance policy blocks the step output             |
| <code>agent_run_failed</code> | The overall agent run ends in a failed state           |

**Default triggers** (when `prompt_model_auto_rollback_triggers` is null): `agent_eval_fail`, `governance_block`, `agent_run_failed`.

### Configuring Auto Upgrade

**Via the App:** Open the agent, go to **Settings → Model Lifecycle**, and choose an upgrade strategy and rollback preferences.

**Via the API:**

```bash
# Enable cautious auto-upgrade with rollback on eval failures and governance blocks
curl -X PUT "https://api.seclai.com/api/agents/$AGENT_ID" \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_model_auto_upgrade_strategy": "cautious_adopter",
    "prompt_model_auto_rollback_enabled": true,
    "prompt_model_auto_rollback_triggers": ["agent_eval_fail", "governance_block"]
  }'

# Disable auto-upgrade
curl -X PUT "https://api.seclai.com/api/agents/$AGENT_ID" \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt_model_auto_upgrade_strategy": "none"}'
```

**Via MCP:** Use the `update_agent` tool with `prompt_model_auto_upgrade_strategy`, `prompt_model_auto_rollback_enabled`, and `prompt_model_auto_rollback_triggers` parameters.

For step-level overrides, set `auto_upgrade_strategy`, `auto_rollback_enabled`, and `auto_rollback_triggers` directly in the step definition via `update_agent_definition`. See [Agent Steps: Model Lifecycle Controls](https://seclai.com/docs/agent-steps/core#model-lifecycle-controls) for field details.

---

## API Access

All model lifecycle features are available via the REST API with API key authentication:

```
# Get replacement recommendations for a model
curl "https://api.seclai.com/api/models/{model_id}/recommendations" \
  -H "X-API-Key: $SECLAI_API_KEY"

# Get recommendations with capability filters
curl "https://api.seclai.com/api/models/{model_id}/recommendations?require_tool_use=true&min_context_tokens=100000" \
  -H "X-API-Key: $SECLAI_API_KEY"

# List model lifecycle alerts
curl "https://api.seclai.com/api/models/alerts" \
  -H "X-API-Key: $SECLAI_API_KEY"

# List unread alerts for a specific agent
curl "https://api.seclai.com/api/models/alerts?agent_id=$AGENT_ID&unread_only=true" \
  -H "X-API-Key: $SECLAI_API_KEY"

# Get unread alert count
curl "https://api.seclai.com/api/models/alerts/unread-count" \
  -H "X-API-Key: $SECLAI_API_KEY"

# Dismiss a single alert
curl -X PATCH "https://api.seclai.com/api/models/alerts/$ALERT_ID/read" \
  -H "X-API-Key: $SECLAI_API_KEY"

# Dismiss all alerts
curl -X POST "https://api.seclai.com/api/models/alerts/mark-all-read" \
  -H "X-API-Key: $SECLAI_API_KEY"
```

## MCP Access

Model lifecycle tools are available through the MCP (Model Context Protocol) server for use with agentic coding tools:

| Tool                                   | Description                                     |
| -------------------------------------- | ----------------------------------------------- |
| <code>get_model_recommendations</code> | Get replacement/upgrade suggestions for a model |
| <code>list_model_alerts</code>         | List model lifecycle alerts with filtering      |
| <code>dismiss_model_alert</code>       | Mark a single alert as read                     |
| <code>dismiss_all_model_alerts</code>  | Mark all alerts as read                         |

These tools use the same API key authentication as all other MCP tools.

## Next Steps

- [Alerts](https://seclai.com/docs/alerts) — Configure all alert types including model lifecycle alerts
- [Agents](https://seclai.com/docs/agents) — Learn about creating and configuring agents
- [API Examples](https://seclai.com/docs/api-examples) — More API usage examples
- [Dashboard](https://seclai.com/docs/dashboard) — Monitor aggregated metrics for your account