---
title: "AI Assistant 2.2.0 migration guide"
canonical_url: "https://www.nutrient.io/guides/ai-assistant/migration-guides/ai-assistant-2-2-0-migration-guide/"
md_url: "https://www.nutrient.io/guides/ai-assistant/migration-guides/ai-assistant-2-2-0-migration-guide.md"
last_updated: "2026-06-18T00:00:00.000Z"
description: "Migrate AI Assistant from version 2.1.0 to 2.2.0, including JWT user_id claim changes and model service override updates."
---

# AI Assistant 2.2.0 migration guide

This guide outlines the changes required to migrate AI Assistant from version `2.1.0` to `2.2.0`.

## Breaking change: user_id JWT claim required for rate limiting

Previously, the `userId` field in the client configuration (Web SDK or V2 API) was used as the identity for rate limiting. This meant a client could supply any `userId` on each request, making it possible to bypass rate limits.

Starting in `2.2.0`, the `user_id` claim in the JSON Web Token (JWT) is the authoritative user identity for rate limiting. **Rate limiting now requires the `user_id` claim to be set in the JWT.**

### Migration steps

1. **If you use rate limiting** (`request_limit` claim in the JWT) — Add a `user_id` claim to the JWT with the user’s identifier. Without it, the server will return a `401` error.

2. **If you pass `userId` in the client configuration** — If the JWT also includes a `user_id` claim, the two values must match. A mismatch will return a `401` error. Either remove `userId` from the client configuration, or ensure it matches the JWT `user_id` claim.

3. **If you don’t use rate limiting or `userId`** — No changes are required.

### JWT before and after

Before:

```json

{
  "document_ids": ["doc-1"],
  "request_limit": {
    "requests": 100,
    "time_period_s": 3600
  }
}

```

After:

```json

{
  "document_ids": ["doc-1"],
  "user_id": "user-abc-123",
  "request_limit": {
    "requests": 100,
    "time_period_s": 3600
  }
}

```

### Additional details

- The `user_id` claim must be a non-empty string.

- The `user_id` is stored as thread metadata for audit and ownership tracking.

- See the [JWT claims](https://www.nutrient.io/guides/ai-assistant/viewer-integration/client-authentication/generate-a-jwt.md) guide for full details on all supported claims.

## Deprecated: modelOverrides and model_overrides

AI Assistant 2.2.0 deprecates the `modelOverrides` request field and the `agent_configuration.model_overrides` JWT claim. Existing requests continue to work because the server translates them into the new `modelServices.models` shape, but new integrations should use `modelServices` and `agent_configuration.model_services`.

### Migration steps

1. Replace JWT `agent_configuration.model_overrides` with `agent_configuration.model_services.models`.

2. Replace request `modelOverrides` with `context.modelServices.models`.

3. Don’t send both `modelOverrides` and `modelServices` in the same request. Doing so returns a `400` error.

### JWT claim before and after

Before:

```json

{
  "agent_configuration": {
    "model_overrides": {
      "default-llm": ["openai:*"]
    }
  }
}

```

After:

```json

{
  "agent_configuration": {
    "model_services": {
      "models": {
        "default-llm": ["openai:*"]
      }
    }
  }
}

```

`model_services.models` supports the same model allowlist patterns as `model_overrides`: exact models, provider wildcards such as `"openai:*"`, and the full wildcard `"*"`.

### Request body before and after

Before:

```json

{
  "config": {
    "configurable": {
      "modelOverrides": {
        "default-llm": "openai:gpt-4o"
      }
    }
  }
}

```

After:

```json

{
  "context": {
    "modelServices": {
      "models": [
        {
          "labels": ["default-llm"],
          "model": "openai:gpt-4o"
        }
      ]
    }
  }
}

```

## MCP error handling change

Missing model context protocol (MCP) servers now surface as API errors instead of warnings. If you configure MCP servers, verify they’re reachable and correctly authenticated before upgrading.
---

## Related pages

- [AI Assistant 2.1.0 migration guide](/guides/ai-assistant/migration-guides/ai-assistant-2-1-0-migration-guide.md)