> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Lifecycle Management

> Set expiry dates, review schedules, and assign sponsors to enforce agent lifecycle governance

Agent lifecycle management ensures that every AI agent has an expiry date, a review schedule, and a responsible sponsor. Expired and unreviewed agents surface automatically so you can decommission stale agents and enforce periodic access reviews.

## Lifecycle Fields

| Field              | Type                                               | Description                                   |
| ------------------ | -------------------------------------------------- | --------------------------------------------- |
| `expires_at`       | ISO 8601 datetime                                  | When the agent authorization expires          |
| `review_frequency` | `weekly` \| `monthly` \| `quarterly` \| `annually` | How often the agent must be reviewed          |
| `sponsor_id`       | string                                             | The person or team responsible for this agent |

## Set Agent Lifecycle

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH https://api.meshai.dev/api/v1/agents/01ARZ3NDEKTSV4RRFFQ69G5FAV/lifecycle \
    -H "Authorization: Bearer msh_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "expires_at": "2026-06-30T23:59:59Z",
      "review_frequency": "quarterly",
      "sponsor_id": "ml-platform-team"
    }'
  ```

  ```python SDK theme={null}
  from meshai import MeshAI

  client = MeshAI(api_key="msh_...")

  client.set_agent_lifecycle(
      agent_id="01ARZ3NDEKTSV4RRFFQ69G5FAV",
      expires_at="2026-06-30T23:59:59Z",
      review_frequency="quarterly",
      sponsor_id="ml-platform-team",
  )
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "expires_at": "2026-06-30T23:59:59Z",
      "review_date": "2026-06-18T00:00:00Z",
      "review_frequency": "quarterly",
      "sponsor_id": "ml-platform-team"
    }
  }
  ```
</ResponseExample>

You can set any combination of fields - all are optional. Only the fields you include are updated.

## List Expired Agents

Returns agents whose `expires_at` date has passed. Use this to identify agents that need decommissioning or renewal.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.meshai.dev/api/v1/agents/expired \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  expired = client.list_expired_agents()
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "01F8MECHZX3TBDSZ7XR8H8JHAF",
        "name": "legacy-support-bot",
        "expires_at": "2026-02-28T23:59:59Z"
      }
    ]
  }
  ```
</ResponseExample>

This endpoint returns a plain list - it is not paginated and does not include `sponsor_id`, `status`, or `days_expired`.

## List Agents Due for Review

Returns agents whose next review date has passed or is approaching. Use this to enforce periodic access reviews.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.meshai.dev/api/v1/agents/due-review \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  due = client.list_agents_due_review()
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "name": "customer-support-agent",
        "review_date": "2026-03-15T00:00:00Z",
        "review_frequency": "quarterly"
      }
    ]
  }
  ```
</ResponseExample>

This endpoint also returns a plain, unpaginated list, without `sponsor_id` or `days_overdue`.

## Review Frequency Options

| Frequency   | Review interval |
| ----------- | --------------- |
| `weekly`    | Every 7 days    |
| `monthly`   | Every 30 days   |
| `quarterly` | Every 90 days   |
| `annually`  | Every 365 days  |

The `review_date` is automatically calculated as now plus the review interval whenever `review_frequency` is set or changed.

## Audit Trail

Lifecycle changes (setting `expires_at`, `review_frequency`, or `sponsor_id`) do not currently emit their own audit event.

## Use Cases

* **Compliance** - EU AI Act requires periodic review of high-risk AI systems. Set `review_frequency` to `quarterly` for high-risk agents.
* **Shadow agent cleanup** - Set short expiry dates on newly discovered agents to force review.
* **Team accountability** - Assign `sponsor_id` so every agent has a responsible owner.
* **Decommissioning workflow** - Poll `GET /agents/expired` and call the [kill switch](/governance/kill-switch) yourself to block agents past their expiry; MeshAI does not auto-block expired agents today.